Frictional Wiki - User contributions [en]

HPL2/HPL2 Helper Scripts

2024-03-03T07:27:04Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

The current version is [[HPL2/HPL2_Helper_Scripts#Version_1.1.2C_03.2F02.2F24|1.1]].

Once you have unzipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetSegmentHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusicTracked(), StopMusicTracked(), IsMusicPlaying(), DuckStart(), DuckRestore()
** New properties in cFader: IsMusicPlaying, MusicPlayingCount
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2024-02-11T03:21:41Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

The current version is [[HPL2/HPL2_Helper_Scripts#Version_1.1.2C_03.2F02.2F24|1.1]].

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetSegmentHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusicTracked(), StopMusicTracked(), IsMusicPlaying(), DuckStart(), DuckRestore()
** New properties in cFader: IsMusicPlaying, MusicPlayingCount
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts/Fader

2024-02-11T03:20:11Z

Mrbehemo: Added IsMusicPlaying, MusicPlayingCount, IsMusicPlaying(), StartMusicTracked(), StopMusicTracked(), DuckStart(), DuckRestore(), and added more intro info.

{{TocRight}}
This page documents "HelperScripts_Fader.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script class cFader manages a list of sound entities in a level that are set to play ambient sounds.

The intent is that, rather than having many localised ambient sounds around the level, the level designer can use a handful of sound entities to provide a non-3d "soundscape" and then use scripting to switch between them, and layer them to the desired extent.

Fader handles the fading so that sounds are not cut off suddenly if, for example, a player moves repeatedly over a trigger. Since we can't smoothly change a fade that is already in progress, Fader waits and applies new changes as soon as possible, with the idea that smooth fading is more important than accurate timing.

===Initialising loops===
For Fader to control a looping sound, the sound entity (placed in the map in Level Editor) must be registered with Fader. This is done using InitLoop(), typically in the OnEnter() callback of the level.
<syntaxhighlight lang="cpp">
void OnEnter()
{
Fader.InitLoop("MySound");
}
</syntaxhighlight>

===Groups and Priority===
Each Fader sound can be assigned a group. Only one sound from each group can play at a time. This can be used to build up a layered soundscape and swap out a specific layer. If the group is zero, that counts as "no group". Multiple group-zero sounds can play at once.
 Each Fader sound is also assigned a priority, or prio. If the maximum number of sounds are player and another tries to play, a random sound with the lowest priority will fade out. The StopLowPriority() method can also be used to manually stop the lowest priority sounds.

===Music===
Fader doesn't do anything special with regards to playing music files, but when the music is stopped and started via Fader using PlayMusicTracked() and StopMusicTracked(), then Fader can keep track of it. Fader sounds can be marked as "StopOnMusic" so that they can fade out when music starts. The basic script functions don't provide a way to query whether music is playing, but Fader provides the properties IsMusicPlaying and MusicPlayingCount.

===Ducking===
Fader sounds that are currently playing can be temporarily faded out and back in using DuckStart() and DuckRestore(). This could be useful for cutscenes or dramatic moments.

===Sound files===
Ideally, .snt files for use with Fader should have the following settings:
<syntaxhighlight lang="cpp">
FadeEnd="True" FadeStart="True" Stream="True" Loop="True" Use3D="False" Blockable="False"
</syntaxhighlight>
(In theory, Fader will work ''to a certain extent'' with any other .snt file settings, but not as intended. This has not been tested.)

===Save data===
Fader saves its data for each level to GameVars so that it can be automatically restored when the player returns to the level or reloads a game that was saved in the level. Any sounds that were initialised with Fader at the time of saving will be re-initialised, and their play state will be restored.

The restoration of the loaded state occurs on the first frame once the game has started. If the game starts and Fader hasn't yet been initialised, then it will check to see if there is saved data from a previous session, and restore it. If the game starts and Fader was already initialised in OnStart() or OnEnter(), then the load will be skipped.

===Advanced info===
'''Advanced users''' may wish to examine "HelperScripts_Fader.hps" to see how it makes use of other script classes. There are also some private variables that could to tweaked to fit the needs of a specific project, such as the maximum concurrent sounds and the default fade times.

=Fader=
Fader is the name of the object that manages the sound fading.

==Behaviours==
"HelperScripts_Fader.hps" declares an object called '''Fader''', of the new script class cFader. To access its properties and methods, just use "Fader." followed by the function call or property. E.g.:
<syntaxhighlight lang="cpp">
Fader.InitLoop("ForestAmbienceLoop");
if (Fader.IsAnyPlaying) DoStuff();
</syntaxhighlight>

==Properties==
Fader provides the following properties:

====SoundsCount====
<syntaxhighlight lang="cpp">
uint SoundsCount
</syntaxhighlight>
The read-only integer property SoundsCount returns the number of sounds registered with Fader.
<syntaxhighlight lang="cpp">
// Example:
if (Fader.SoundsCount == 0) Fader.InitLoop("ForestAmbienceLoop");
// The condition succeeds if no sounds have been registered with Fader yet, and the first one is registered in response.
</syntaxhighlight>

====SoundsPlayingCount====
<syntaxhighlight lang="cpp">
uint SoundsPlayingCount
</syntaxhighlight>
The read-only integer property SoundsPlayingCount returns the number of Fader sounds that are currently playing.
<syntaxhighlight lang="cpp">
// Example:
if (Fader.SoundsPlayingCount > 5) StopMusic(10.0f, 1);
// The condition succeeds if there are more than 5 Fader sounds currently playing, in which case the music is faded out.
</syntaxhighlight>

====IsAnyPlaying====
<syntaxhighlight lang="cpp">
bool IsAnyPlaying
</syntaxhighlight>
The read-only boolean property IsAnyPlaying returns whether there are currently any Fader sounds playing.
<syntaxhighlight lang="cpp">
// Example:
if (Fader.IsAnyPlaying) DoStuff();
// The condition succeeds if any Fader sound is currently playing or fading in.
</syntaxhighlight>

====IsMusicPlaying====
<syntaxhighlight lang="cpp">
bool IsMusicPlaying
</syntaxhighlight>
The read-only boolean property IsMusicPlaying returns whether music is currently playing, as long as the music was started or stopped by Fader. See also the IsMusicPlaying() method, to check if music is playing at a specific music prio.

====MusicPlayingCount====
<syntaxhighlight lang="cpp">
uint MusicPlayingCount
</syntaxhighlight>
The read-only uint property MusicPlayingCount returns the number of music tracks currently playing. (If there are tracks with different prio values, only the one with the highest prio will be heard, but the rest will also be considered "playing".)

==Methods==
Fader provides the following methods:

===Adding/removing loops===

====InitLoop()====
<syntaxhighlight lang="cpp">
bool InitLoop(string asNewSound, bool abStartImmediately = false)
bool InitLoop(string asNewSound, bool abStartImmediately, float afFadeInTime = 2.5f, float afFadeOutTime = 2.5f, const afPriority = 1.0f, uint aulGroup = 0, bool abStopOnMusic = false)
</syntaxhighlight>
Sets up a sound entity in the map to be controlled by Fader, typically during the OnEnter() callback of the level. asNewSound is the name of the sound entity as named in the Level Editor. Returns true if the sound was successfully added. abStartImmediately is optional and can be omitted. If true, the sound will fade in ASAP, otherwise it be ready to start later.
 afFadeInTime and afFadeOutTime can be used to assign longer or short transitions to this sound, but you can also omit it and Fader will use the defaults instead.
 afPriority is optional. If omitted it defaults to mfPriorityDefault (1.0f). The priority of a sound is used if a sound needs to be removed from play. The sound chosen to be stopped will be one with the lowest priority value (and the oldest if there are equal lowest priorities).
 aulGroup is also optional. If specified with a value greater than zero, this serves to group sounds together into channels. Normally sounds layer on top when they start to play, but only one sound with the same aulGroup number greater than zero can play at once. The new sound will replace others with the same aulGroup.
 abStopOnMusic is also option. It defaults to false if omited. If true, this sound will fade out whenever music starts that is tracked by Fader.
#''string asNewSound'' - The name of the sound entity in the map (not the .snt file).
#''bool abStartImmediately'' - Whether the sound should be playing from the start. (Optional, default = false)
#''float afFadeInTime'' - Used to override the default fade timing for this sound. (Optional together with afFadeOutTime, default = 2.5f)
#''float afFadeInTime'' - Used to override the default fade timing for this sound. (Optional together with afFadeInTime, default = 2.5f)
#''float afPriority'' - How important is this sound? Lowest priority sounds get replaced first. (Optional, default = 1.0f)
#''uint aulGroup'' - If > 0, only one sound in each group can play at once. (Optional, default = 0)
#''bool abStopOnMusic'' - If true, the sound will fade out whenever music is playing that is tracked by Fader. (Optional, default = false)
<syntaxhighlight lang="cpp">
// Example 1:
Fader.InitLoop("CitySounds");
// The sound entity "CitySounds" is registered with Fader, with default settings.

// Example 2:
Fader.InitLoop("BasementCreaks", false, 4.0f, 8.0f, 2.0f);
// The sound entity "BasementCreaks" is registered with Fader, with specific fade times and priority.

// Example 3:
Fader.InitLoop("MountainWindQuiet", true, 1.0f, 2);
Fader.InitLoop("MountainWindLoud", false, 2.0f, 2);
// Two complementary sounds are registered. Since they are in the same group (2), only one of them can play at once.
// If Fader ever has to decide which one of the two it should stop, it will chose "MountainWindQuiet" as it has the lower priority.
</syntaxhighlight>

====ClearAllLoops()====
<syntaxhighlight lang="cpp">
void ClearAllLoops()
</syntaxhighlight>
De-registers all registered sounds. Since sounds are typically added once with InitLoop() when the player enters the level, ClearAllLoops() should only be needed in exceptional cases. Does not change the current play state of the actual sound loops.
<syntaxhighlight lang="cpp">
// Example:
Fader.InitLoop("NiceSounds");
Fader.InitLoop("SpookySounds", true);
Fader.ClearAllLoops();
// Both the "NiceSounds" and "SpookySounds" entities are de-registered. Since "SpookySounds" was set to start playing, it will probably continue playing without Fader.
</syntaxhighlight>

===Starting/stoppping sounds===

====StartLoop()====
<syntaxhighlight lang="cpp">
bool StartLoop(string asStartLoop)
bool StartLoop(string asStartLoop, float afOverrideFadeTime)
</syntaxhighlight>
Starts a loop playing as soon as possible. Returns true if the sound was successfully prepared to start.
 Optionally, you can override the fade-in time for the sound with afOverrideFadeTime. If omitted, the sound's default fade time will be used if it has one, or the Fader default fade time if it doesn't.
#''string asStartLoop'' - Name of the sound entity in the map to start playing.
#''float afOverrideFadeTime'' - Overrides the fade time for the sound. (Optional, default = default fade time)
<syntaxhighlight lang="cpp">
// Example 1:
Fader.StartLoop("canyon.mid");
// If there is a Fader sound with the name "canyon.mid", it will fade in and play, with its default fade time.

// Example 2:
Fader.StartLoop("roblox_oof_10hourloop", 60.0f);
// If there is a Fader sound with the name "roblox_oof_10hourloop", it will fade in and play over the course of a minute.
</syntaxhighlight>

====StopLoop()====
<syntaxhighlight lang="cpp">
void StopLoop(string asSoundToRemove)
</syntaxhighlight>
If the specified sound is currently playing, this will stop it as soon as possible.
#''string asSoundToRemove'' - The name of the sound entity to be stopped in the map.
<syntaxhighlight lang="cpp">
// Example:
Fader.StopLoop("lofi_beats_to_hide_from_grunts_to");
// If there is a Fader sound with the name "lofi_beats_to_hide_from_grunts_to" and if it is currently playing, it will fade out and stop.
</syntaxhighlight>

====StopAllLoops()====
<syntaxhighlight lang="cpp">
void StopAllLoops()
</syntaxhighlight>
Stops all playing sounds as soon as possible.
<syntaxhighlight lang="cpp">
// Example:
Fader.StopAllLoops();
// Any sounds that are currently playing will fade out and stop.
</syntaxhighlight>

====StopLowPriority()====
<syntaxhighlight lang="cpp">
void StopLowPriority()
void StopLowPriority(float afThreshold)
</syntaxhighlight>
Checks the priority of currently playing sounds, and if any of them have a priority less than or equal to the specified value, they will be stopped as soon as possible.
 If afThreshold is omitted, a sound with the lowest prority will be removed.
#''float afThreshold'' - Any sounds with this priority or less will be stopped. (Optional, default is lowest priorty)
<syntaxhighlight lang="cpp">
// Example 1:
Fader.StopLowPriority(2.0f);
// Any currently playing sounds with a priority of 2.0f or less will fade out and stop.

// Example 2:
if (Fader.SoundsPlayingCount >= lTooManySounds) Fader.StopLowPriority();
// If the number of sounds playing is greater than the limit set by lTooManySounds, then a single low-priority sound will fade out and stop.
</syntaxhighlight>

====StopGroup()====
<syntaxhighlight lang="cpp">
void StopGroup(uint aulGroup)
</syntaxhighlight>
Checks the group number of currently playing sounds, and if any of them have the specified group number, they will be stopped as soon as possible.
#''uint aulGroup'' - Any sounds with this group number will be stopped.
<syntaxhighlight lang="cpp">
// Example:
Fader.StopGroup(4);
// All sounds in group 4 will fade out and stop.
</syntaxhighlight>

====DuckStart()====
<syntaxhighlight lang="cpp">
void DuckStart()
</syntaxhighlight>
Fades out all currently playing sounds, storing them in a temporary list. DuckRestore() can be used to resume the sounds that have been ducked. Calling DuckStart() again (before DuckRestore()) will erase the list.
<syntaxhighlight lang="cpp">
// Example:
Fader.StartLoop("lofiBeats");
// a short while later
Fader.DuckStart();
// a while later still
Fader.DuckRestore();
// The sound named "lofiBeats" will start, duck and then restore.
</syntaxhighlight>

====DuckRestore()====
<syntaxhighlight lang="cpp">
void DuckStart()
</syntaxhighlight>
Resumes sounds that have been temporarily stoped by DuckStart(), and clears the temporary list. Any Fader sounds that were started since DuckStart() will be stopped.
<syntaxhighlight lang="cpp">
// Example:
Fader.StartLoop("lofiBeats");
// a short while later
Fader.DuckStart();
// a while later still
Fader.DuckRestore();
// The sound named "lofiBeats" will start, duck and then restore.
</syntaxhighlight>

===Music===

====PlayMusicTracked()====
<syntaxhighlight lang="cpp">
void PlayMusicTracked(string asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume)
</syntaxhighlight>
Starts music, same as the global function Fader.PlayMusicTracked(), only this method is tracked by Fader and can affect Fader sounds.

====StopMusicTracked()====
<syntaxhighlight lang="cpp">
void StopMusicTracked(float afFadeTime, int alPrio)
</syntaxhighlight>
Stops music, same as the global function Fader.StopMusicTracked(), only this method is tracked by Fader and can affect Fader sounds.

====IsMusicPlaying()====
<syntaxhighlight lang="cpp">
bool IsMusicPlaying( int alPrio)
</syntaxhighlight>
Returns true if music is playing with the given priority. See also the IsMusicPlaying and MusicPlayingCount properties.

===Querying sounds===

====IsLoopPlaying()====
<syntaxhighlight lang="cpp">
bool IsLoopPlaying(string asLoop)
</syntaxhighlight>
Given the name of a sound entity in the map, this returns true if it is currently playing in Fader.
 "Currently playing" includes fading in, but not fading out. If the sound has not been initialised as a Fader loop, this will return false regardless of whether it is actually playing.
#''string asLoop'' - The name of the sound entity to check.
<syntaxhighlight lang="cpp">
// Example:
if (Fader.IsLoopPlaying("DistantMusic")) DoStuff();
// The condition succeeds if the sound "DistantMusic" is currently playing.
</syntaxhighlight>

====DebugOutput()====
<syntaxhighlight lang="cpp">
void DebugOutput()
</syntaxhighlight>
Writes the current state of all registered Fader loops as a Debug message with priority 3.
 

=cFaderSound=
cFaderSound is a list node class used by cFader to manage individual loops. It is '''not recommended''' to work with cFaderSound directly. Instead, just use the methods of Fader and let it manage them for you.

'''Advanced users''' who intend to access cFaderSound instances may find the following information useful.

==Behaviours==
cNodeBobbing has three constructors, from full control to minimal args that use default settings:
<syntaxhighlight lang="cpp">
cFaderSound(string asName)
cFaderSound(string asName, enumFaderState aFaderState)
cFaderSound(string asName, float afFadeInTime, float afFadeOutTime, float afPriority, uint aulGroup, enumFaderState aFaderState)
</syntaxhighlight>

==Fields==
cFaderSound has no public properties, but is does have some public fields: <code>string msName; uint mulGroup; enumFaderState mFaderState;</code>

=Miscellaneous=

===Global functions===
"HelperScripts_Fader.hps" defines five global timer callbacks used by cFader to handle latent fading. It is '''not recommended''' to work with cFaderSound directly. Instead, just use the methods of Fader and let it manage them for you.
<syntaxhighlight lang="cpp">
void Fader_StartLoop_LatentRetry(string &in asRetrySound)
void Fader_StartFocus_LatentDone(string &in asFadedSound)
void Fader_Play_LatentRetry(string &in asFadedSound)
void Fader_StopFocus_LatentDone(string &in asFadedSound)
void Fader_Stop_LatentRetry(string &in asFadedSound)
</syntaxhighlight>

===Enums===
"HelperScripts_Fader.hps" defines the enumerator enumFaderState.

__FORCETOC__

HPL2/HPL2 Helper Scripts/Glitcher

2024-02-11T02:46:35Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Glitcher.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script class cGlitcher manages a list of entity groups that should appear to erratically twitch and move, without any animated models or shaders.

===Glitch entities===
One "''glitch''" contains at least one entity which, at semi-random intervals, should move to a slightly different position. The multiple entities within a glitch a here called "alt entities" or "alts".

If the glitch contains only one alt entity, it will only "twitch" without changing. If multiple entities are added to the glitch, then they will be substituted. The entities can be different types: for example, multiple versions of a statue, in slightly different poses. Or they can just be a different scale or rotation, which can have a similar effect.

Furthermore, glitches containing mutliple entities will quickly fade between alts rather than switching instantly. Glitches contain only one alt must twitch instantly without any fading. The fade time reduces as the intensity of the glitching increases.

===Intensity===
The amount of the glitching is controlled by Glitcher's ''intensity'' calculations. Intensity affects the interval and likelihood of glitches occuring, as well that the smoothness of the entities fading as they are substituted.

Itensity responds to the player's Sanity level, but it can also be controlled influenced in script with SetIntensity() method. The Intensity property can be used to check what the current intensity level is.

===Player distance===
Each glitching entity can have a specific distance that the player must be within for the glitches to occur. When the player is beyond this distance, the glitching will pause. The level designer should balance the player distance against the size of the entity, the visibility of the glitches, and the size of the space the player might see it in. The default distance is 24.0f units, but this can be overridden in the Add() arguments.

===Save data===
Glitcher saves its data for each level to GameVars so that it can be automatically restored when the player returns to the level or reloads a game that was saved in the level. Any entities that were registered with Glitcher at the time of saving will be re-registered and their glitching state will be restored. The restoration of the loaded state occurs on the first frame once the game has started. If the game starts and Glitcher hasn't yet been initialised, then it will check to see if there is saved data from a previous session, and restore it. If the game starts and Glitcher was already initialised in OnStart() or OnEnter(), then the load will be skipped.

===Advanced info===
'''Advanced users''' may wish to examine "HelperScripts_Glitcher.hps" to see how it makes use of other script classes. There are also some private variables that could to tweaked to fit the needs of a specific project, such as default player distance, maximum number of glitchers, and the default numbers involved in the intensity and fading calculations.

=Glitcher=
Glitcher is the name of the object that manages the glitching entities.

==Behaviours==
"HelperScripts_Glitcher.hps" declares an object called '''Glitcher''', of the new script class cGlitcher. To access its properties and methods, just use "Glitcher." followed by the function call or property. E.g.:
<syntaxhighlight lang="cpp">
if (Glitcher.IsEntGlitching("IllusionThing"))
Glitcher.Intensity = 1.0f;
</syntaxhighlight>

==Properties==
Glitcher provides the following properties:

====IsActive====
<syntaxhighlight lang="cpp">
bool IsActive
</syntaxhighlight>
The read-only boolean property IsActive returns whether there are currently any active glitches.
<syntaxhighlight lang="cpp">
// Example:
if (Glitcher.IsActive) DoStuff();
// The condition succeeds if Glitcher is currently glitching some entities.
</syntaxhighlight>

====Intensity====
<syntaxhighlight lang="cpp">
float Intensity
</syntaxhighlight>
The read-only float property Intensity returns the current intensity value resulting from the sanity bias and min-max intensities. If no glitches are currently active, the intensity value will be zero.
<syntaxhighlight lang="cpp">
// Example:
if (Glitcher.Intensity > 0.5f) DoStuff();
// The condition succeeds if Glitcher intensity is over 50%.
</syntaxhighlight>

====FadeDuration====
<syntaxhighlight lang="cpp">
float FadeDuration
</syntaxhighlight>
The read-only float property FadeDuration returns the current fading time resulting from the sanity bias and min-max intensities. If no glitches are currently active, the returned value will be zero.
<syntaxhighlight lang="cpp">
// Example:
FadeLightTo("someLight", 1.0f, 0.6f, 0.4f, 1.0f, 12.0f, Glitcher.FadeDuration);
// This example imagines that the level designer wants a light to fade with the same speed a glitching entities.
</syntaxhighlight>

====GlitchCount====
<syntaxhighlight lang="cpp">
uint GlitchCount
</syntaxhighlight>
The read-only integer property GlitchCount returns the number of glitches that have been registered in Glitcher.
<syntaxhighlight lang="cpp">
// Example:
if (Glitcher.GlitchCount > 8) ClearGlitches();
// The condition succeeds if Glitcher is currently glitching more than eight entities.
</syntaxhighlight>

==Methods==
Glitcher provides the following methods:

===Adding glitches===

====Add()====
<syntaxhighlight lang="cpp">
bool Add(string asEntAltOne, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
bool Add(string asEntAltOne, string asEntAltTwo, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
bool Add(string asEntAltOne, string asEntAltTwo, string asEntAltThree, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
bool Add(string[] asEntAlts, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
bool Add(cListString asEntAlts, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
</syntaxhighlight>
Registers an entity or multiple entities as a glitch. Returns true if the glitch was successfully added.
 Entity names can be provided as one, two or three individual strings, or array of strings, or a cListString.
 afJitterScale is optional. If omitted it defaults to 1.0f. The jitter scale multiplies the distance an entity can move when it twitches. The default jitter scale of 1.0 means movements of up to 5cm.
 afChanceScale is optional. If omitted it defaults to 1.0f. The chance scale multiplies the likelihood that a glitch will occur at each interval.
 Also optionally, the player distance and glitch sounds can be overridden. Otherwise the Glitcher defaults are used.
#''string asEntAltOne, string[] asEntAlts, cListString asEntAlts'' - The name of an entity, an array of entity names, or a list of entity names to include in the glitch as alt entities.
#''string asEntAltTwo'' - If specifying entities as individual strings, this is a second entity to include. (Optional)
#''string asEntAltThree'' - If specifying entities as individual strings, this is a third entity to include. (Optional)
#''float afJitterScale'' - Multiplies the distance that the mesh can move when it twitches. (Optional, default = 1.0f)
#''float afChanceScale'' - Multiplies the likelihood that a glitch will occur on each interval. (Optional, default = 1.0f)
#''float afMaxPlayerDist'' - If using an array of strings, afMaxPlayerDist can be used to override the default player distance for this glitch. (Optional, default = 24.0f)
#''float asGlitchSound'' - If using an array of strings, asGlitchSound can be used to override the default sound played when a glitch occurs. (Optional, default = "", no sound)
<syntaxhighlight lang="cpp">
// Example 1:
Glitcher.Add("SpookyTree1", "SpookyTree2", 10.0f, 50.0f, "forest_tree_creak.snt");
// A glitch is created with two alt entities.
// The jitter scale is 10.0f, which means that each twitch could be up to 0.5m.
// The max player distance is 50.0f, which would allow the movement to be see from afar.
// The glitch is assigned a sound to play on each twitch.

// Example 2:
cListString listStatueA;
listStatueA.Add("statue_A_0");
listStatueA.Add("statue_A_1");
listStatueA.Add("statue_A_2");
listStatueA.Add("statue_A_3");
Glitcher.Add(listStatueA);
// A glitch is created with default settings, using alt entities listed in listStatueA.

// Example 3:
Glitcher.Add(String.StringRange("statue_A_", 0, 3, ""));
// The StringRange() method is used to produce a list of entity names - the outcome is the same as example 2.
</syntaxhighlight>

====AddSeries()====
<syntaxhighlight lang="cpp">
bool AddSeries(string asPrefix, uint aulPostfixDigits = 0, float afJitterScale = 1.0f, float afChanceScale = 1.0f, float afMaxPlayerDist = 24.0f, string asGlitchSound = "")
</syntaxhighlight>
Registers a series of named entities as a glitch. Returns true if the glitch was successfully added.
 AddSeries() is useful when the alt entities have a regular naming pattern but it is unknown at the time of scripting how many there will be. Entity names are provided in the format "someNamePrefix1". The first part of the name is asPrefix. The number is an index from 0 to 128. AddSeries() counts from 0 and stops when it comes to an entity that doesn't exist.
 aulPostfixDigits can be used optionally to specify leading zeroes in the entity names. For example, if the entity names are formatted as "someNamePrefix01" then aulPostfixDigits should be 2.
 afJitterScale is optional. If omitted it defaults to 1.0f. The jitter scale multiplies the distance an entity can move when it twitches. The default jitter scale of 1.0 means movements of up to 5cm.
 afChanceScale is optional. If omitted it defaults to 1.0f. The chance scale multiplies the likelihood that a glitch will occur at each interval.
 Also optionally, the player distance and glitch sounds can be overridden. Otherwise the Glitcher defaults are used.
#''string asPrefix'' - The first part of an entity name, to be appended with an index.
#''uint aulPostfixDigits'' - The number of digits to expect in an entity name, including leading zeroes. (Optional, default = 0, no leading zeroes)
#''float afJitterScale'' - Multiplies the distance that the mesh can move when it twitches. (Optional, default = 1.0f)
#''float afChanceScale'' - Multiplies the likelihood that a glitch will occur on each interval. (Optional, default = 1.0f)
#''float afMaxPlayerDist'' - If using an array of strings, afMaxPlayerDist can be used to override the default player distance for this glitch. (Optional, default = mfDefaultMaxPlayerDist)
#''float asGlitchSound'' - If using an array of strings, asGlitchSound can be used to override the default sound played when a glitch occurs. (Optional, default = "", no sound)
<syntaxhighlight lang="cpp">
// Example:
// Example 1:
Glitcher.AddSeries("SpookyTree", 1.0f, 0.5f);
// A glitch is created with as many alt entities as are found matching the pattern "SpookyTree0", "SpookyTreek1" etc..
// The chance scale provided is 50%, so this glitcher is half as likely to twitch than default.

// Example 2:
Glitcher.Add("statue_A_", 3);
// A glitch is created with default settings, with as many alt entities as are found matching the pattern "statue_A_0", "statue_A_1" etc..
</syntaxhighlight>

===Adding glitches from Slimer===

====AddFromSlimer_InstsToSingles()====
<syntaxhighlight lang="cpp">
bool AddFromSlimer_InstsToSingles(string asSequence)
</syntaxhighlight>
Registers a series of entities as a glitch, using the default settings. The entities are sourced from Slimer. If sequences of entities have been prepared for use in Slimer, this method allows them to be passed easily to Glitcher. Note that the glitch state may override the sequence state and vice versa.
 In particular, AddFromSlimer_InstsToSingles() creates glitches with a single alt entity in each. Each of the instance entities in the specified sequence becomes an individual glitch with only one alt.
 Returns true if the glitch was successfully added.
#''string asSequence'' - The name of the Slimer sequence to add.
<syntaxhighlight lang="cpp">
// Example:
Glitcher.AddFromSlimer_InstsToSingles("CutsceneSequenceA");
// Each of the entities registered with Slimer for the sequence "CutsceneSequenceA" is now registered with Glitcher.
// Each individual Slimer instance entity has become an individual glitch with a single alt.
</syntaxhighlight>

====AddFromSlimer_StepsToAlts()====
<syntaxhighlight lang="cpp">
bool AddFromSlimer_StepsToAlts(string asSequence)
</syntaxhighlight>
Registers a series of entities as a glitch, using the default settings. The entities are sourced from Slimer. If sequences of entities have been prepared for use in Slimer, this method allows them to be passed easily to Glitcher. Note that the glitch state may override the sequence state and vice versa.
 In particular, AddFromSlimer_StepsToAlts() creates glitches with multiple alt entities in each. The Slimer steps in the specified sequence become individual glitches, and the instance entities in each of the steps become the alts.
 Returns true if the glitch was successfully added.
#''string asSequence'' - The name of the Slimer sequence to add.
<syntaxhighlight lang="cpp">
// Example:
Glitcher.AddFromSlimer_InstsToSingles("CutsceneSequenceA");
// Each of the entities registered with Slimer for the sequence "CutsceneSequenceA" is now registered with Glitcher.
// Each individual Slimer step has become a glitch with multiple alts.
</syntaxhighlight>

===Resetting/removing glitches===

====ClearGlitches()====
<syntaxhighlight lang="cpp">
void ClearGlitches()
</syntaxhighlight>
Cancels all registered glitches and empties the list. Does not return entities to their original states.
<syntaxhighlight lang="cpp">
// Example:
Glitcher.ClearGlitches();
// All registered glitches are cleared but no entity changes were made.
</syntaxhighlight>

====ResetAll()====
<syntaxhighlight lang="cpp">
void ResetAll(bool abHideAllEnts = false)
</syntaxhighlight>
Cancels all registered glitches and empties the list, and resets intensity variables to their defaults.
 Does not return entities to their original states, but if abHideAllEnts is true, all registered entities will be set as inactive. abHideAllEnts is optional and defaults to false if omitted.
#''bool abHideAllEnts'' - If true, all registered glitch entities will be hidden. (Optional, default = false)
<syntaxhighlight lang="cpp">
// Example:
Glitcher.ResetAll(true);
// All registered glitches are cleared, intensity variable are reset, and any entities that were part of a glitch have been hidden.
</syntaxhighlight>

===Intensity===

====SetIntensity()====
<syntaxhighlight lang="cpp">
void SetIntensity(float afIntensity)
void SetIntensity(float afMin, float afMax, float afSanityBias, float afSanityExp = 1.5f)
</syntaxhighlight>
Overrides the intensity range and calculations. If only one float is specified, that will become the actual exact intensity used, with influence from player Sanity.
 Optionally, the min, max and sanity bias can be specified. The min and max limit the intensity value by clamping the inverted sanity. Sanity bias defines how much influence player sanity has on the final intensity. If sanity bias is 1, the intensity will be equal to the inverse of sanity clamped to the min and max. If the bias is 0, the intensity will be equal to the mid point of the min and max. The default value for the bias is 0.666.
 An optional sanity exponent can also be specified. The default value is 1.5. This is the exponent that is applied to the inverse of sanity, adding a to curve the relationship between sanity and intensity. Higher afSanityExp values mean that when the player sanity is high, the intensity is less changeable but when the player sanity gets low, the glitch intensity will increase more suddenly.
#''float afIntensity or float afMin'' - Either the exact intensity value to used, or the minimum limit of player Sanity to influence intensity.
#''float afMax'' - The the maximum limit of player Sanity to influence intensity. (Optional with afMin and afSanityBias)
#''float afSanityBias'' - The extent (0.0 - 1.0) that player Sanity should influence intensity. (Optional with afMax and afSanityBias, default = 0.666f)
#''float afSanityExp'' - The exponent to apply to Sanity. (0.0 - 1.0) that player Sanity should influence intensity. (Optional with afMin, afMax and afSanityBias, default = 1.5f)
<syntaxhighlight lang="cpp">
// Example 1:
Glitcher.SetIntensity(0.5f);
Glitcher.SetIntensity(0.5f, 0.5f, 0.0f);
// These two lines have the same effect. Intensity is manually set to 50%, regardless of player Sanity.

// Example 2:
Glitcher.SetIntensity(0.0f, 0.5f, 1.0f);
// Intensity is limited between 0% - 50%, and player Sanity has 100% influence. (Sanity exponent is default 1.5f.)
// If Sanity is 100% Intensity = 0%
// If Sanity is 80% Intensity = 20%
// If Sanity is 60% Intensity = 50%
// If Sanity is 40% Intensity = 50%
// If Sanity is 20% Intensity = 50%
// If Sanity is 0% Intensity = 50%

// Example 2:
Glitcher.SetIntensity(0.0f, 0.5f, 0.25f);
// Intensity is limited between 0% - 50%, ''but player Sanity only has 25% influence''. (Sanity exponent is default 1.5f.)
// If Sanity is 100% Intensity = 19%
// If Sanity is 80% Intensity = 21%
// If Sanity is 60% Intensity = 25%
// If Sanity is 40% Intensity = 35%
// If Sanity is 20% Intensity = 35%
// If Sanity is 0% Intensity = 35%

// Example 3:
Glitcher.SetIntensity(0.0f, 0.6f, 1.0f, 0.5f);
// Intensity is limited between 0% - 60%, and player Sanity has 100% influence. ''Sanity exponent is reduced to 0.5f, so intensity rises sharply.''
// If Sanity is 100% Intensity = 0%
// If Sanity is 80% Intensity = 45%
// If Sanity is 60% Intensity = 63%
// If Sanity is 40% Intensity = 78%
// If Sanity is 20% Intensity = 78%
// If Sanity is 0% Intensity = 78%
</syntaxhighlight>

====ResetIntensity()====
<syntaxhighlight lang="cpp">
void ResetIntensity()
</syntaxhighlight>
Returns all intensity values to their defaults. (Min = 0.0f, Max = 1.0f, Bias = 0.666f, Exp = 1.5f)
<syntaxhighlight lang="cpp">
// Example:
Glitcher.ResetIntensity();
// Min, max intensity and sanity bias and exponent have been reset.
</syntaxhighlight>

===Querying glitches===

====IsEntGlitching()====
<syntaxhighlight lang="cpp">
bool IsEntGlitching(string asEntity)
</syntaxhighlight>
Returns true if the named entity already exists as one alt in a glitch in the glitch list.
#''string asEntity'' - The entity to check for.
<syntaxhighlight lang="cpp">
// Example:
if (Glitcher.IsEntGlitching("statue_1A")) DoStuff();
// The condition succeeds if the entity "statue_1A" is part of a registered glitch.
</syntaxhighlight>

=cNodeGlitching=
cNodeGlitching is a list node class used by cGlitcher to manage individual glitches. It is '''not recommended''' to work with cNodeGlitching directly. Instead, just use the methods of Glitcher and let it manage them for you.

'''Advanced users''' who intend to access cNodeGlitching instances may find the following information useful.

==Behaviours==
cNodeGlitching has constructors taking an array of entity names, or taking a single entity name. Both have an alternative version with additional args.
<syntaxhighlight lang="cpp">
cNodeGlitching(string asAltName)
cNodeGlitching(string asAltName, float afJitterScale float afChanceScale float afMaxPlayerDist string asGlitchSound)
cNodeGlitching(string[] asAltNames)
cNodeGlitching(string[] asAltNames, float afJitterScale, float afChanceScale, float afMaxPlayerDist, string asGlitchSound)
</syntaxhighlight>

==Properties==
cNodeBobbing has the following properties:

====IsActive====
<syntaxhighlight lang="cpp">
bool IsActive
</syntaxhighlight>
The read-only boolean property IsActive ''updates'' whether the bobber should be active based on the player distance and returns the result.
 

====CurrentAltIndex====
<syntaxhighlight lang="cpp">
uint CurrentAltIndex
</syntaxhighlight>
The read-only integer property CurrentAltIndex returns the index of this glitch's current alt entity.
 

====CurrentAltName====
<syntaxhighlight lang="cpp">
string CurrentAltName
</syntaxhighlight>
The read-only string property CurrentAltName returns the index of this glitch's current alt entity.
 

====AltNames====
<syntaxhighlight lang="cpp">
string[] AltNames
</syntaxhighlight>
The read-only string array property AltNames returns a handle to this glitch's array of alt entity names.
 

====NumberOfAlts====
<syntaxhighlight lang="cpp">
uint NumberOfAlts
</syntaxhighlight>
The read-only integer property NumberOfAlts gets the number of alt entities that have been registered to this glitch.
 

====JitterDist====
<syntaxhighlight lang="cpp">
float JitterDist
</syntaxhighlight>
The read-only float property JitterDist returns how far the glitch can move on each twitch.
 

====ChanceScale====
<syntaxhighlight lang="cpp">
float ChanceScale
</syntaxhighlight>
The read-only float property ChanceScale returns likelihood that this glitch will twitch at each interval.
 

====PlayerDistSqr====
<syntaxhighlight lang="cpp">
float PlayerDistSqr
</syntaxhighlight>
The read-only float property PlayerDistSqr returns the square of the maximum player distance to animate this glitch.
 

====GlitchSound====
<syntaxhighlight lang="cpp">
string GlitchSound
</syntaxhighlight>
The read-only string property GlitchSound returns the glitch's sound filename.
 

===Methods===

====CheckActive()====
<syntaxhighlight lang="cpp">
bool CheckActive()
</syntaxhighlight>
Updates whether the glitcher should be active based on the player distance and returns the result.
 

====SelectNextAlt()====
<syntaxhighlight lang="cpp">
uint SelectNextAlt()
</syntaxhighlight>
Selects a alternate entity and assigns it as the current alt. If there is only one alt, no change is made. If there are only two alts, they will alternate (flip-flop). If there are more than two alts, then a random one will be selected. The current alt is excluded so that it won't be chosen twice. (Yes, the definition of "alternate" means that there are two states, so the concept of "alt entities" here is technically erroneous.)
 

====DoGlitch()====
<syntaxhighlight lang="cpp">
void DoGlitch(float afIntensity, float afFadeDuration, float afFadeDelay)
</syntaxhighlight>
If a random chance succeeds (based on the intensity and fChanceScale), then this selects a new alt entity and applies the twitch.
#''float afIntensity'' - The current intensity, passed from cGlitcher.
#''float afFadeDuration'' - The current fading time, passed from cGlitcher.
#''float afFadeDelay'' - The current time to wait before fading in, passed from cGlitcher.
 

=Miscellaneous=

===Global functions===
"HelperScripts_Glitcher.hps" defines a global timer callback, used by cGlitcher to handle latent entity fading. It is '''not recommended''' to work with these directly. Instead, just use the methods of Glitcher and let it manage them for you.
<syntaxhighlight lang="cpp">
void GlitcherLatentFade(string &in asTimer)
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Vectors

2024-02-11T02:43:22Z

Mrbehemo: Added cBezier GetSegmentHandle() and GetMinLength()

{{TocRight}}
This page documents "HelperScripts_Vectors.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Vectors.hps" adds support for various vector classes. For beginners or other people not familiar with classes, this is best thought of as new variable types.

At its simplest, vector is a type holds multiple numbers, and is usually used to represent spatial co-ordinates or movement. Some advantages to using a vector over individual numbers is that you can pass the vector as a single argument, or use it in arithmetic as if it was single scalar number. For example:
<syntaxhighlight lang="cpp">
// Example 1 - The basic way:
float fSpeedX = 1.5f;
float fSpeedY = 0.0f;
float fSpeedZ = 0.75f;
float fCurrentX = GetEntityPosX("myEntity");
float fCurrentY = GetEntityPosY("myEntity");
float fCurrentZ = GetEntityPosZ("myEntity");
SetEntityPos("myEntity", fCurrentX + (fSpeedX * afStep), fCurrentY + (fSpeedY * afStep), fCurrentZ + (fSpeedZ * afStep));

// Example 2 - The Helper Scripts way:
cVector vSpeed = new cVector(1.5f, 0.0f, 0.75f);
cVector vCurrent = GetEntityPosVec("myEntity");
SetEntityPosVec("myEntity", vCurrent + (vSpeed * afStep));
</syntaxhighlight>

These two examples have the same effect, but with much simpler code.

Various methods are provided, in both the vector classes and in Math, for working with vectors; for example, to find out the length of a line, working out rotations, plotting paths and more.

===Vector types===
Available vector classes:
<code>cVector</code>, <code>cPoint</code>, <code>cRotator</code>, <code>cBezier</code>, <code>cSpline</code>

===The basics===
Declare a vector like any other variable, and use its various properties, operations and methods list on this page to work with it. For example:
<syntaxhighlight lang="cpp">
cVector myVector; // Declares a new cVector, called myVector. By default it's a 3d vector.
cVector my2dVector(2); // Declares a new cVector, set up to have 2 dimensions.
cVector myVector.X = 2.0f; // Assigns the value 2.0f to the X component of myVector.
</syntaxhighlight>
The cPoint and cRotator classes work similarly. (A cPoint is a vector containing integers instead of floats, and a cRotator is a vector intended for working with pitch-yaw-roll rotations.

===Component properties===
The simplest way to access the components of a 2d or 3d vector is through the named properties. A 2d or 3d cVector provides X and Y, or X, Y and Z properties. cRotator has Pitch, Yaw and Roll. See the notes below for more details on each class.

===Indices===
Like arrays, you can ''get'' the items in the vector using an index operator, e.g. myVector[0], myVector[1], myVector[2] are the same as the X, Y and Z properties. However, ''unlike arrays'', this is '''read-only'''.

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
cRotator inherits from cVector. Advanced users who want to make their own derived vector types are advised to read over the cVector definition and derived class definitions to see how they inherit.

cVector and cPoint can both be used for 2d or 3d vectors. The vector classes are designed to be agnostic of dimensionality. The maximum number of dimensions for all vector classes is defined by ulVectorDimMax. The default value is 16, but an advanced user may want to edit that value. cVector and it's derived classes can have any number of dimensions from 0 to, in theory, 65535, although either extreme would be ridiculous. Using a maximum larger than 65535 could cause problems.

Arithmetic, and some methods, can work with differently dimensioned vectors. For example <code>a[X,Y,Z] + b[X,Y]</code> has the same effect as <code>a[X,Y,Z] + b[X,Y,0]</code>.

=cVector=
The cVector class defines a type that contains a series of float values, typically used to represent a spatial location or movement.

==Behaviours==
cVectors are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cVector myVector;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cVector myVector; // Makes a 3d vector
cVector myVector = cVector(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cVector myVector = cVector(3); // Makes a 3d vector

cVector myVector = cVector(2); // Makes a 2d vector
cVector myVector = cVector(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cVector provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
float X
</syntaxhighlight>
The float property X provides access to the first component in the cVector (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.X;
vMyVector.X = 1.0f;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
float Y
</syntaxhighlight>
The float property Y provides access to the second component in the cVector (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Y;
vMyVector.Y = 1.0f;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
float Z
</syntaxhighlight>
The float property Z provides access to the third component in the cVector (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Z;
vMyVector.Z = 1.0f;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
float W
</syntaxhighlight>
The float property W provides access to the fourth component in the cVector (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.W;
vMyVector.W = 1.0f;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cVector. The dimension of the cVector can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyVector.Dimension >=3) vMyVector.Z = 0.0f;
// The condition succeeds if the cVector has at least three components, and then the value of the 3rd component is assigned 0.0f.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cVector. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
float fMyFloat = vMyVector[vMyVector.LastIndex];
// The float fMyFloat is assigned whatever value is found in the final component of the cVector.
</syntaxhighlight>

==Operators==

Some '''arithmetic''' operators have been implemented for '''a cVector with another cVector''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cVector with a float''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Using <code>*</code> or <code>/</code> to multiply or divide a vector by a scalar value (float or double) will scale the vector, component-wise.
 Using <code>*</code> to multiply a scalar value by a vector (ie. reversing the order) provides the same componenet-wise result. E.g.:
<syntaxhighlight>[1.0, 2.0, 3.0] * 1.5 = [1.5, 3.0, 4.5]
1.5 * [1.0, 2.0, 3.0] = [1.5, 3.0, 4.5]</syntaxhighlight>
But of course, reversing the order with <code>/</code> will return a different result. E.g.:
<syntaxhighlight>[1.0, 2.0, 3.0] / 2.0 = [0.5, 1.0, 1.5]
2.0 / [1.0, 2.0, 3.0] = [2.0, 1.0, 0.666666]</syntaxhighlight>
As of version 1.1, using <code>*</code> to multiply two vectors together will return the two vectors multiplied component-wise. E.g.:
<syntaxhighlight>[2.0, 2.0, 2.0] * [2.0, 0.0, 0.25] = [4.0, 0.0, 0.5]</syntaxhighlight>
 As of version 1.1, using <code>/</code> to divide two vectors will return the first vectors divided by the second vector, component-wise, using safe divide. E.g:
<syntaxhighlight>[2.0, 2.0, 2.0] / [2.0, 0.0, 0.25] = [1.0, 0.0, 8.0]</syntaxhighlight>
 (Prior to version 1.1, * would return the dot product and / was not implemented. In version 1.1, the dot product can be calculated with the DotProduct() method instead.)

The '''equality''' operator <code> == </code> checks for an exact match between two cVectors. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cVector provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, float afValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''float afValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetIndex(1, 3.0f);
vMyVector.Y = 3.0f;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir2d(dirLeft);
// vMyVector becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir3d(dirLeft);
// vMyVector becomes 1,0,0
</syntaxhighlight>

===Getting values===
cVector provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
float GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.GetIndex(2);
fMyFloat = vMyVector.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cVector provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
float Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a float. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cVector vMyRectangle = cVector(10.0f, 15.0f);
float fMyHypotenuse = vMyRectangle.Length();
// fMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
float LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cVector Normal()
</syntaxhighlight>
Calculates the normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal() * fSpeed;
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of exactly fSpeed.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become 1.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Vector products===

====DotProduct()====
<syntaxhighlight lang="cpp">
float DotProduct(cVector avB)
</syntaxhighlight>
Calculates the dot product of this and the given vector avB, and returns it as a float.
#''cVector avB'' - The other vector.

====CrossProduct()====
<syntaxhighlight lang="cpp">
cVector CrossProduct(cVector avB)
</syntaxhighlight>
Caulculates the cross product of this and the given vector avB, and returns it as a new vector.
#''cVector avB'' - The other vector.

===Strings from cVector===
cVector provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cVector" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cVector by one, and adds the given float as a new component.
bool Append(cVector avValues) // Increases the dimension of this cVector to accomodate the given cVector, and appends its components.
const float[]@ ReadArray() // Returns a handle to the cVector's component array data.
</syntaxhighlight>

=cPoint=
The cPoint class defines a vector type that contains a series of int values, typically used to represent a location or movement on a grid, or pixels.

==Behaviours==
cPoints are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cPoint myPoint;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cPoint myPoint; // Makes a 3d vector
cPoint myPoint = cPoint(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cPoint myPoint = cPoint(3); // Makes a 3d vector

cPoint myPoint = cPoint(2); // Makes a 2d vector
cPoint myPoint = cPoint(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cPoint provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
int X
</syntaxhighlight>
The integer property X provides access to the first component in the cPoint (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.X;
vMyPoint.X = 1;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
int Y
</syntaxhighlight>
The integer property Y provides access to the second component in the cPoint (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Y;
vMyPoint.Y = 1;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
int Z
</syntaxhighlight>
The integer property Z provides access to the third component in the cPoint (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Z;
vMyPoint.Z = 1;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
int W
</syntaxhighlight>
The integer property W provides access to the fourth component in the cPoint (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.W;
vMyPoint.W = 1;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cPoint. The dimension of the cPoint can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyPoint.Dimension >=3) vMyPoint.Z = 0;
// The condition succeeds if the cPoint has at least three components, and then the value of the 3rd component is assigned 0.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cPoint. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
int fMyInt = vMyPoint[vMyPoint.LastIndex];
// The int fMyInt is assigned whatever value is found in the final component of the cPoint.
</syntaxhighlight>

==Operators==

Note: the results of division operations with ints maybe truncated. That is, in integer calculations, 1 / 2 = 0.

'''Arithmetic''' operators have been implemented for '''a cPoint with another cPoint''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cPoint with an int''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

The '''multiplication''' operator <code>*</code> used with a cPoint and an int, or a pair of cPoint, will scale the point component-wise.

The '''equality''' operator <code> == </code> checks for an exact match between two cPoints. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cPoint provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, int alValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''int alValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetIndex(1, 3);
vMyPoint.Y = 3;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir2d(dirLeft);
// vMyPoint becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir3d(dirLeft);
// vMyPoint becomes 1,0,0
</syntaxhighlight>

===Getting values===
cPoint provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
int GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.GetIndex(2);
fMyInt = vMyPoint.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cPoint provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
int Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a truncated int. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cPoint vMyRectangle = cPoint(10, 15);
int lMyHypotenuse = vMyRectangle.Length();
// lMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
int LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cPoint Normal()
</syntaxhighlight>
Calculates the truncated integer normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of approximately one, while the components remain whole numbers.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal();
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of approximately one.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of approximately one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become approximately one.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Strings from cPoint===
cPoint provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cPoint" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cPoint by one, and adds the given float as a new component.
bool Append(cPoint avValues) // Increases the dimension of this cPoint to accomodate the given cPoint, and appends its components.
const int[]@ ReadArray() // Returns a handle to the cPoint's component data array.
</syntaxhighlight>

=cRotator=
The cRotator class defines a type that contains a series of float values, intended to represent an angular orientation, or a rotation. cRotator inherits from cVector, but also defines some properties and methods specific to working with rotation.

==Behaviours==
There are two ways to assign the pitch, yaw and roll values in the constructor.

1. The angle values can be set directly in the constructor using degrees or radians. An optional enumAngleUnits is used to specify whether using degrees. The default is radians.
<syntaxhighlight lang="cpp">
// Initialising angles in degrees:
cRotator(pitchDegrees, yawDegrees, rollDegrees, angleDegrees)

// Initialise the angles in radians
cRotator(pitchRadians, yawRadians, rollRadians)
cRotator(pitchRadians, yawRadians, rollRadians, angleRadians)

// These two rotators are equivalent:
cRotator myDegrees = cRotator(90.0f, 180.0f, 45.0f, true);
cRotator myRadians = cRotator(Math.Pi, Math.Tau, Math.Pi / 2.0f);
</syntaxhighlight>

2. The angle values can be set in the constructor using an enumOrthoDir option. enumOrthoDir can be dirForward, dirBackward, dirLeft, dirRight, dirUp, or dirDown.
<syntaxhighlight lang="cpp">
cRotator yawRight = cRotator(dirRight);
cRotator pitchDown = cRotator(dirDown);
</syntaxhighlight>

==Properties==
The angle values can be set with the Pitch, Yaw and Roll properties:
<syntaxhighlight lang="cpp">
myRotator.Pitch = Math.Pi / 2.0f;
</syntaxhighlight>

The pitch, yaw and roll properties are treated as radians by default. To specify degrees or radians explicitly, the pitchDeg, yawDeg, rollDeg, and pitchRad, yawRad, rollRad properties can be used, e.g.:
<syntaxhighlight lang="cpp">
myRotator.YawDeg = 180;
myRotator.RollRad = Math.Pi * 3.0f;
</syntaxhighlight>

Internally the cRotator class stores angle values as radians between negative and positive Pi. (Equivalent to -180 degrees to 180 degrees.) Angles outside of this range are wrapped around. E.g.:
<syntaxhighlight lang="cpp">
cRotator rotation = cRotator(0.0f, 90.0f, 0.0f, true);
rotation += cRotator(0.0f, 120.0f, 0.0f, true);
// rotation is now (degrees) 0.0f, -150.0f, 0.0f
</syntaxhighlight>

In this example, "rotation" is initialised with 90d yaw, and then rotated a further
120d clockwise. Rather than 210d clockwise, the resulting yaw is 150 anti-clockwise (-150);

====Pitch====
<syntaxhighlight lang="cpp">
float Pitch
float PitchRad
float PitchDeg
</syntaxhighlight>
The float properties Pitch and PitchRad provide access to the pitch component in radians. PitchDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Pitch;
vMyRotator.PitchDeg = 90.0f;
</syntaxhighlight>

====Yaw====
<syntaxhighlight lang="cpp">
float Yaw
float YawRad
float YawDeg
</syntaxhighlight>
The float properties Yaw and YawRad provide access to the pitch component in radians. YawDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Yaw;
vMyRotator.YawDeg = 90.0f;
</syntaxhighlight>

====Roll====
<syntaxhighlight lang="cpp">
float Roll
float RollRad
float RollDeg
</syntaxhighlight>
The float properties Roll and RollRad provide access to the pitch component in radians. RollDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Roll;
vMyRotator.RollDeg = 90.0f;
</syntaxhighlight>

==Methods==
In addition to methods inherited from cVector, cRotator provides the following methods:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
string ToStringRad()
</syntaxhighlight>
Returns the components of the vector as radians in a string with the format "(p=_, y=_, r=_)(rad)".
 

====ToStringDeg()====
<syntaxhighlight lang="cpp">
string ToStringDeg()
</syntaxhighlight>
Returns the components of the vector as degrees in a string with the format "(p=_, y=_, r=_)(deg)".
 

=cBezier=

The cBezier class defines a curved line in space, with a couple of basic functions. Technically it is a cubic bezier defined by 4 points: a start, an end, and two control points for influencing the curve. It can also roughly approximate a quadratic bezier if constructed with only one control point.

==Behaviours==
cBezier has four constructors:

<syntaxhighlight lang="cpp">
cBezier(cVector avStart, cVector avCtrl1, cVector avCtrl2, cVector avEnd) // Creates a cubic bezier with two control points.
cBezier(cVector avStart, cVector avCtrl, cVector avEnd) // Creates bezier approximating a quadratic bezier.
cBezier(cVector avStart, cVector avEnd) // Creates a bezier that behaves like a straight line.
cBezier() // Creates a bezier that starts and ends at 0,0,0, with zero length.
</syntaxhighlight>

==Properties:==
To access the internal vector positions in the bezier, you can use the properties: Start, End, CtrlStart and CtrlEnd.
<syntaxhighlight lang="cpp">
cBezier manualBezier;
cVector someLocation = cVector(10.0f, 11.0f, 12.0f);
manualBezier.Start = someLocation;
manualBezier.End = someLocation * 1.5f;
</syntaxhighlight>

====Start====
<syntaxhighlight lang="cpp">
cVector Start
</syntaxhighlight>
The cVector property Start can be used to get or set the start point of the curve with a 3d cVector.

====End====
<syntaxhighlight lang="cpp">
cVector End
</syntaxhighlight>
The cVector property End can be used to get or set the end point of the curve with a 3d cVector.

====CtrlStart====
<syntaxhighlight lang="cpp">
cVector CtrlStart
</syntaxhighlight>
The cVector property CtrlStart can be used to get or set the first control point of the curve with a 3d cVector.

====CtrlEnd====
<syntaxhighlight lang="cpp">
cVector CtrlEnd
</syntaxhighlight>
The cVector property CtrlEnd can be used to get or set the second control point of the curve with a 3d cVector.

==Methods==
cBezier provides the following methods:

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMyBezier.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the curve.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMyBezier.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the curve at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the curve.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the bezier as a string, including the x,y,z components of all four vector positions.

=cSpline=

The cSpline class defines an array of Beziers that can be treated like a continuous path made of multiple curved segments. Internally cSpline is a cBezier array of a fixed maximum size (default = 16). The cSpline can be initialised using existing beziers, or with a single curve defined by args in the constructor.

For further control over how the curve is built, the cSpline can be declare as empty with segments added afterwards. Segments can be added to the spline either as whole cBezier segments using AddSegment(), or by adding one cVector point at a time using AddPoint().

With the AddPoint() method, the spline is defined by providing the positions it should move through as individual points in space. Specific tangents can be provided (forward direction and scale) for each point, but are optional. When the final point is added, abLast should be specified as true to finish the spline and apply automatic tangents where needed. The automatic tangents make sure that path through each point is smooth, unless specific tangents were specified through AddPoint().

Alternatively, with the AddSegment() method, the spline can be defined by providing each segment as a Bezier. The end of the previous segment will be updated to match the new one. (This is not quite the same as passing an array of Beziers to the constructor, as in that case the constructor will not attempt to match the end points, and they will not be smooth or even continuous unless defined that way by the script.)

The spline does not have constant velocity. That is to say, each segment has an equal share of the "time", regardless of the size of the segment, and within each segment the control points can cause acceleration. Easing can be effected by varying the size of the segments.

==Behaviours==
cSpline has seven constructors in total, with various options for initialising a curve.

===Constructing empty splines===
If the cSpline should start empty, ready for AddSegment() or AddPoint(), one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline() // Creates an empty spline with a maximum size of 16 bezier segments.
cSpline(uint aulSegments) // Creates an empty spline with capacity for the number of bezier segments specified by aulSegments.
</syntaxhighlight>

===Constructing with cBezier===
If the cSpline should be populated with one or more existing bezier curves, one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline(cBezier aSegmentsArray) // Takes an existing cBezier array and uses that to populate the new spline.
cSpline(cBezier@ ahBezier) // Uses a reference to an existing cBezier to populate the new spline with a single segment.
</syntaxhighlight>

===Constructing with cVector===
Finally, if the cSpline should be populated a curve or line defined by cVector arguments, one of these constructors will help:
<syntaxhighlight lang="cpp">
cSpline(cVector avStart, cVector avCtrlStart, cVector avCtrlEnd, cVector avEnd)
// Takes four vector positions and builds a cubic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avCtrl, cVector avEnd)
// Takes three vector positions and builds a approximation of a quadratic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avEnd)
// Takes two vector positions and populate the new spline with a single segment in the form of a straight line between two points.
</syntaxhighlight>

==Methods==
cBezier provides the following methods:

====AddSegment()====
<syntaxhighlight lang="cpp">
bool AddSegment(cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Appends a bezier onto the spline as new segment. Returns false if the spline is already full, or true if it was successfully added.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment will be adjusted to connect to the start point and entrance tangent of the new one.
#''cBezier ahSegment'' - A bezier to be appended to the spline.
#''bool abSnap'' - Whether to adjust the previous segment to connect to the new one. (Optional, default = true)

====GetSegmentHandle()====
<syntaxhighlight lang="cpp">
cBezier@ GetSegmentHandle(uint aulIndex)
</syntaxhighlight>
Looks up the spline segment at the give index and returns a handle to its cBezier.
#''uint aulIndex'' - The index of the segment to be returned.

====UpdateSegment()====
<syntaxhighlight lang="cpp">
bool UpdateSegment(uint aulIndex, cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Updates an existing segment by index, replacing it with a new bezier. Returns false if the segment does not already exist, or true if it was successfully updated.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment, and the start point and entrance tangent of the next segment will be adjusted to connect to the updated segment.
#''uint aulIndex'' - The index of the segment to be replaced.
#''cBezier ahSegment'' - A bezier to be replace the bezier at the given index. to the spline.
#''bool abSnap'' - Whether to adjust the previous and next segments to connect to the updated one. (Optional, default = true)

====AddPoint()====
<syntaxhighlight lang="cpp">
bool AddPoint(bool abLast = false, cVector avNextPosition, cVector avNextTangent)
bool AddPoint(bool abLast = false, cVector avNextPosition)
</syntaxhighlight>
Appends a position to the end of the spline. Returns false if the spline is already full, or true if it was successfully added.
 avNextTangent is optional and can be omitted. It specifies the tangent as the velocity (direction and scale) of the spline at the new point. If omitted, no tangent is used at this time, but once you have finished adding points, abLast = true should be used and automatic tangents will be applied at that time.
 The automatic tangents are only applied to points where no tangent was given, and only once the spine is marked as "finished" by using abLast = true;
#''bool abLast'' - Whether this is the last point to be added. (Optional, default = false)
#''cVector avNextPosition'' - A position in space to add to the spline.
#''cVector avNextTangent'' - The forward velocity of the spline as it passes through the new position. (Optional, default = auto)

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMySpline.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the spline.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMySpline.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the spline at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the entire spline.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====GetMinLength()====
<syntaxhighlight lang="cpp">
float GetMinLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Returns the minimum length of that the entire spline could be, if each segment was a straight line.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a string describing the spline, including the x,y,z components of its start and end points, and the number of segments.

__FORCETOC__

HPL2/HPL2 Helper Scripts/Vectors

2024-02-11T02:37:39Z

Mrbehemo: Added DotProduct(), CrossProduct(), vector * and /

{{TocRight}}
This page documents "HelperScripts_Vectors.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Vectors.hps" adds support for various vector classes. For beginners or other people not familiar with classes, this is best thought of as new variable types.

At its simplest, vector is a type holds multiple numbers, and is usually used to represent spatial co-ordinates or movement. Some advantages to using a vector over individual numbers is that you can pass the vector as a single argument, or use it in arithmetic as if it was single scalar number. For example:
<syntaxhighlight lang="cpp">
// Example 1 - The basic way:
float fSpeedX = 1.5f;
float fSpeedY = 0.0f;
float fSpeedZ = 0.75f;
float fCurrentX = GetEntityPosX("myEntity");
float fCurrentY = GetEntityPosY("myEntity");
float fCurrentZ = GetEntityPosZ("myEntity");
SetEntityPos("myEntity", fCurrentX + (fSpeedX * afStep), fCurrentY + (fSpeedY * afStep), fCurrentZ + (fSpeedZ * afStep));

// Example 2 - The Helper Scripts way:
cVector vSpeed = new cVector(1.5f, 0.0f, 0.75f);
cVector vCurrent = GetEntityPosVec("myEntity");
SetEntityPosVec("myEntity", vCurrent + (vSpeed * afStep));
</syntaxhighlight>

These two examples have the same effect, but with much simpler code.

Various methods are provided, in both the vector classes and in Math, for working with vectors; for example, to find out the length of a line, working out rotations, plotting paths and more.

===Vector types===
Available vector classes:
<code>cVector</code>, <code>cPoint</code>, <code>cRotator</code>, <code>cBezier</code>, <code>cSpline</code>

===The basics===
Declare a vector like any other variable, and use its various properties, operations and methods list on this page to work with it. For example:
<syntaxhighlight lang="cpp">
cVector myVector; // Declares a new cVector, called myVector. By default it's a 3d vector.
cVector my2dVector(2); // Declares a new cVector, set up to have 2 dimensions.
cVector myVector.X = 2.0f; // Assigns the value 2.0f to the X component of myVector.
</syntaxhighlight>
The cPoint and cRotator classes work similarly. (A cPoint is a vector containing integers instead of floats, and a cRotator is a vector intended for working with pitch-yaw-roll rotations.

===Component properties===
The simplest way to access the components of a 2d or 3d vector is through the named properties. A 2d or 3d cVector provides X and Y, or X, Y and Z properties. cRotator has Pitch, Yaw and Roll. See the notes below for more details on each class.

===Indices===
Like arrays, you can ''get'' the items in the vector using an index operator, e.g. myVector[0], myVector[1], myVector[2] are the same as the X, Y and Z properties. However, ''unlike arrays'', this is '''read-only'''.

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
cRotator inherits from cVector. Advanced users who want to make their own derived vector types are advised to read over the cVector definition and derived class definitions to see how they inherit.

cVector and cPoint can both be used for 2d or 3d vectors. The vector classes are designed to be agnostic of dimensionality. The maximum number of dimensions for all vector classes is defined by ulVectorDimMax. The default value is 16, but an advanced user may want to edit that value. cVector and it's derived classes can have any number of dimensions from 0 to, in theory, 65535, although either extreme would be ridiculous. Using a maximum larger than 65535 could cause problems.

Arithmetic, and some methods, can work with differently dimensioned vectors. For example <code>a[X,Y,Z] + b[X,Y]</code> has the same effect as <code>a[X,Y,Z] + b[X,Y,0]</code>.

=cVector=
The cVector class defines a type that contains a series of float values, typically used to represent a spatial location or movement.

==Behaviours==
cVectors are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cVector myVector;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cVector myVector; // Makes a 3d vector
cVector myVector = cVector(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cVector myVector = cVector(3); // Makes a 3d vector

cVector myVector = cVector(2); // Makes a 2d vector
cVector myVector = cVector(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cVector provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
float X
</syntaxhighlight>
The float property X provides access to the first component in the cVector (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.X;
vMyVector.X = 1.0f;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
float Y
</syntaxhighlight>
The float property Y provides access to the second component in the cVector (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Y;
vMyVector.Y = 1.0f;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
float Z
</syntaxhighlight>
The float property Z provides access to the third component in the cVector (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Z;
vMyVector.Z = 1.0f;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
float W
</syntaxhighlight>
The float property W provides access to the fourth component in the cVector (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.W;
vMyVector.W = 1.0f;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cVector. The dimension of the cVector can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyVector.Dimension >=3) vMyVector.Z = 0.0f;
// The condition succeeds if the cVector has at least three components, and then the value of the 3rd component is assigned 0.0f.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cVector. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
float fMyFloat = vMyVector[vMyVector.LastIndex];
// The float fMyFloat is assigned whatever value is found in the final component of the cVector.
</syntaxhighlight>

==Operators==

Some '''arithmetic''' operators have been implemented for '''a cVector with another cVector''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cVector with a float''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Using <code>*</code> or <code>/</code> to multiply or divide a vector by a scalar value (float or double) will scale the vector, component-wise.
 Using <code>*</code> to multiply a scalar value by a vector (ie. reversing the order) provides the same componenet-wise result. E.g.:
<syntaxhighlight>[1.0, 2.0, 3.0] * 1.5 = [1.5, 3.0, 4.5]
1.5 * [1.0, 2.0, 3.0] = [1.5, 3.0, 4.5]</syntaxhighlight>
But of course, reversing the order with <code>/</code> will return a different result. E.g.:
<syntaxhighlight>[1.0, 2.0, 3.0] / 2.0 = [0.5, 1.0, 1.5]
2.0 / [1.0, 2.0, 3.0] = [2.0, 1.0, 0.666666]</syntaxhighlight>
As of version 1.1, using <code>*</code> to multiply two vectors together will return the two vectors multiplied component-wise. E.g.:
<syntaxhighlight>[2.0, 2.0, 2.0] * [2.0, 0.0, 0.25] = [4.0, 0.0, 0.5]</syntaxhighlight>
 As of version 1.1, using <code>/</code> to divide two vectors will return the first vectors divided by the second vector, component-wise, using safe divide. E.g:
<syntaxhighlight>[2.0, 2.0, 2.0] / [2.0, 0.0, 0.25] = [1.0, 0.0, 8.0]</syntaxhighlight>
 (Prior to version 1.1, * would return the dot product and / was not implemented. In version 1.1, the dot product can be calculated with the DotProduct() method instead.)

The '''equality''' operator <code> == </code> checks for an exact match between two cVectors. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cVector provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, float afValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''float afValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetIndex(1, 3.0f);
vMyVector.Y = 3.0f;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir2d(dirLeft);
// vMyVector becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir3d(dirLeft);
// vMyVector becomes 1,0,0
</syntaxhighlight>

===Getting values===
cVector provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
float GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.GetIndex(2);
fMyFloat = vMyVector.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cVector provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
float Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a float. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cVector vMyRectangle = cVector(10.0f, 15.0f);
float fMyHypotenuse = vMyRectangle.Length();
// fMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
float LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cVector Normal()
</syntaxhighlight>
Calculates the normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal() * fSpeed;
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of exactly fSpeed.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become 1.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Vector products===

====DotProduct()====
<syntaxhighlight lang="cpp">
float DotProduct(cVector avB)
</syntaxhighlight>
Calculates the dot product of this and the given vector avB, and returns it as a float.
#''cVector avB'' - The other vector.

====CrossProduct()====
<syntaxhighlight lang="cpp">
cVector CrossProduct(cVector avB)
</syntaxhighlight>
Caulculates the cross product of this and the given vector avB, and returns it as a new vector.
#''cVector avB'' - The other vector.

===Strings from cVector===
cVector provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cVector" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cVector by one, and adds the given float as a new component.
bool Append(cVector avValues) // Increases the dimension of this cVector to accomodate the given cVector, and appends its components.
const float[]@ ReadArray() // Returns a handle to the cVector's component array data.
</syntaxhighlight>

=cPoint=
The cPoint class defines a vector type that contains a series of int values, typically used to represent a location or movement on a grid, or pixels.

==Behaviours==
cPoints are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cPoint myPoint;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cPoint myPoint; // Makes a 3d vector
cPoint myPoint = cPoint(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cPoint myPoint = cPoint(3); // Makes a 3d vector

cPoint myPoint = cPoint(2); // Makes a 2d vector
cPoint myPoint = cPoint(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cPoint provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
int X
</syntaxhighlight>
The integer property X provides access to the first component in the cPoint (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.X;
vMyPoint.X = 1;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
int Y
</syntaxhighlight>
The integer property Y provides access to the second component in the cPoint (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Y;
vMyPoint.Y = 1;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
int Z
</syntaxhighlight>
The integer property Z provides access to the third component in the cPoint (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Z;
vMyPoint.Z = 1;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
int W
</syntaxhighlight>
The integer property W provides access to the fourth component in the cPoint (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.W;
vMyPoint.W = 1;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cPoint. The dimension of the cPoint can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyPoint.Dimension >=3) vMyPoint.Z = 0;
// The condition succeeds if the cPoint has at least three components, and then the value of the 3rd component is assigned 0.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cPoint. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
int fMyInt = vMyPoint[vMyPoint.LastIndex];
// The int fMyInt is assigned whatever value is found in the final component of the cPoint.
</syntaxhighlight>

==Operators==

Note: the results of division operations with ints maybe truncated. That is, in integer calculations, 1 / 2 = 0.

'''Arithmetic''' operators have been implemented for '''a cPoint with another cPoint''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cPoint with an int''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

The '''multiplication''' operator <code>*</code> used with a cPoint and an int, or a pair of cPoint, will scale the point component-wise.

The '''equality''' operator <code> == </code> checks for an exact match between two cPoints. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cPoint provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, int alValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''int alValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetIndex(1, 3);
vMyPoint.Y = 3;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir2d(dirLeft);
// vMyPoint becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir3d(dirLeft);
// vMyPoint becomes 1,0,0
</syntaxhighlight>

===Getting values===
cPoint provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
int GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.GetIndex(2);
fMyInt = vMyPoint.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cPoint provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
int Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a truncated int. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cPoint vMyRectangle = cPoint(10, 15);
int lMyHypotenuse = vMyRectangle.Length();
// lMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
int LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cPoint Normal()
</syntaxhighlight>
Calculates the truncated integer normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of approximately one, while the components remain whole numbers.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal();
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of approximately one.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of approximately one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become approximately one.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Strings from cPoint===
cPoint provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cPoint" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cPoint by one, and adds the given float as a new component.
bool Append(cPoint avValues) // Increases the dimension of this cPoint to accomodate the given cPoint, and appends its components.
const int[]@ ReadArray() // Returns a handle to the cPoint's component data array.
</syntaxhighlight>

=cRotator=
The cRotator class defines a type that contains a series of float values, intended to represent an angular orientation, or a rotation. cRotator inherits from cVector, but also defines some properties and methods specific to working with rotation.

==Behaviours==
There are two ways to assign the pitch, yaw and roll values in the constructor.

1. The angle values can be set directly in the constructor using degrees or radians. An optional enumAngleUnits is used to specify whether using degrees. The default is radians.
<syntaxhighlight lang="cpp">
// Initialising angles in degrees:
cRotator(pitchDegrees, yawDegrees, rollDegrees, angleDegrees)

// Initialise the angles in radians
cRotator(pitchRadians, yawRadians, rollRadians)
cRotator(pitchRadians, yawRadians, rollRadians, angleRadians)

// These two rotators are equivalent:
cRotator myDegrees = cRotator(90.0f, 180.0f, 45.0f, true);
cRotator myRadians = cRotator(Math.Pi, Math.Tau, Math.Pi / 2.0f);
</syntaxhighlight>

2. The angle values can be set in the constructor using an enumOrthoDir option. enumOrthoDir can be dirForward, dirBackward, dirLeft, dirRight, dirUp, or dirDown.
<syntaxhighlight lang="cpp">
cRotator yawRight = cRotator(dirRight);
cRotator pitchDown = cRotator(dirDown);
</syntaxhighlight>

==Properties==
The angle values can be set with the Pitch, Yaw and Roll properties:
<syntaxhighlight lang="cpp">
myRotator.Pitch = Math.Pi / 2.0f;
</syntaxhighlight>

The pitch, yaw and roll properties are treated as radians by default. To specify degrees or radians explicitly, the pitchDeg, yawDeg, rollDeg, and pitchRad, yawRad, rollRad properties can be used, e.g.:
<syntaxhighlight lang="cpp">
myRotator.YawDeg = 180;
myRotator.RollRad = Math.Pi * 3.0f;
</syntaxhighlight>

Internally the cRotator class stores angle values as radians between negative and positive Pi. (Equivalent to -180 degrees to 180 degrees.) Angles outside of this range are wrapped around. E.g.:
<syntaxhighlight lang="cpp">
cRotator rotation = cRotator(0.0f, 90.0f, 0.0f, true);
rotation += cRotator(0.0f, 120.0f, 0.0f, true);
// rotation is now (degrees) 0.0f, -150.0f, 0.0f
</syntaxhighlight>

In this example, "rotation" is initialised with 90d yaw, and then rotated a further
120d clockwise. Rather than 210d clockwise, the resulting yaw is 150 anti-clockwise (-150);

====Pitch====
<syntaxhighlight lang="cpp">
float Pitch
float PitchRad
float PitchDeg
</syntaxhighlight>
The float properties Pitch and PitchRad provide access to the pitch component in radians. PitchDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Pitch;
vMyRotator.PitchDeg = 90.0f;
</syntaxhighlight>

====Yaw====
<syntaxhighlight lang="cpp">
float Yaw
float YawRad
float YawDeg
</syntaxhighlight>
The float properties Yaw and YawRad provide access to the pitch component in radians. YawDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Yaw;
vMyRotator.YawDeg = 90.0f;
</syntaxhighlight>

====Roll====
<syntaxhighlight lang="cpp">
float Roll
float RollRad
float RollDeg
</syntaxhighlight>
The float properties Roll and RollRad provide access to the pitch component in radians. RollDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Roll;
vMyRotator.RollDeg = 90.0f;
</syntaxhighlight>

==Methods==
In addition to methods inherited from cVector, cRotator provides the following methods:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
string ToStringRad()
</syntaxhighlight>
Returns the components of the vector as radians in a string with the format "(p=_, y=_, r=_)(rad)".
 

====ToStringDeg()====
<syntaxhighlight lang="cpp">
string ToStringDeg()
</syntaxhighlight>
Returns the components of the vector as degrees in a string with the format "(p=_, y=_, r=_)(deg)".
 

=cBezier=

The cBezier class defines a curved line in space, with a couple of basic functions. Technically it is a cubic bezier defined by 4 points: a start, an end, and two control points for influencing the curve. It can also roughly approximate a quadratic bezier if constructed with only one control point.

==Behaviours==
cBezier has four constructors:

<syntaxhighlight lang="cpp">
cBezier(cVector avStart, cVector avCtrl1, cVector avCtrl2, cVector avEnd) // Creates a cubic bezier with two control points.
cBezier(cVector avStart, cVector avCtrl, cVector avEnd) // Creates bezier approximating a quadratic bezier.
cBezier(cVector avStart, cVector avEnd) // Creates a bezier that behaves like a straight line.
cBezier() // Creates a bezier that starts and ends at 0,0,0, with zero length.
</syntaxhighlight>

==Properties:==
To access the internal vector positions in the bezier, you can use the properties: Start, End, CtrlStart and CtrlEnd.
<syntaxhighlight lang="cpp">
cBezier manualBezier;
cVector someLocation = cVector(10.0f, 11.0f, 12.0f);
manualBezier.Start = someLocation;
manualBezier.End = someLocation * 1.5f;
</syntaxhighlight>

====Start====
<syntaxhighlight lang="cpp">
cVector Start
</syntaxhighlight>
The cVector property Start can be used to get or set the start point of the curve with a 3d cVector.

====End====
<syntaxhighlight lang="cpp">
cVector End
</syntaxhighlight>
The cVector property End can be used to get or set the end point of the curve with a 3d cVector.

====CtrlStart====
<syntaxhighlight lang="cpp">
cVector CtrlStart
</syntaxhighlight>
The cVector property CtrlStart can be used to get or set the first control point of the curve with a 3d cVector.

====CtrlEnd====
<syntaxhighlight lang="cpp">
cVector CtrlEnd
</syntaxhighlight>
The cVector property CtrlEnd can be used to get or set the second control point of the curve with a 3d cVector.

==Methods==
cBezier provides the following methods:

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMyBezier.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the curve.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMyBezier.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the curve at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the curve.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the bezier as a string, including the x,y,z components of all four vector positions.

=cSpline=

The cSpline class defines an array of Beziers that can be treated like a continuous path made of multiple curved segments. Internally cSpline is a cBezier array of a fixed maximum size (default = 16). The cSpline can be initialised using existing beziers, or with a single curve defined by args in the constructor.

For further control over how the curve is built, the cSpline can be declare as empty with segments added afterwards. Segments can be added to the spline either as whole cBezier segments using AddSegment(), or by adding one cVector point at a time using AddPoint().

With the AddPoint() method, the spline is defined by providing the positions it should move through as individual points in space. Specific tangents can be provided (forward direction and scale) for each point, but are optional. When the final point is added, abLast should be specified as true to finish the spline and apply automatic tangents where needed. The automatic tangents make sure that path through each point is smooth, unless specific tangents were specified through AddPoint().

Alternatively, with the AddSegment() method, the spline can be defined by providing each segment as a Bezier. The end of the previous segment will be updated to match the new one. (This is not quite the same as passing an array of Beziers to the constructor, as in that case the constructor will not attempt to match the end points, and they will not be smooth or even continuous unless defined that way by the script.)

The spline does not have constant velocity. That is to say, each segment has an equal share of the "time", regardless of the size of the segment, and within each segment the control points can cause acceleration. Easing can be effected by varying the size of the segments.

==Behaviours==
cSpline has seven constructors in total, with various options for initialising a curve.

===Constructing empty splines===
If the cSpline should start empty, ready for AddSegment() or AddPoint(), one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline() // Creates an empty spline with a maximum size of 16 bezier segments.
cSpline(uint aulSegments) // Creates an empty spline with capacity for the number of bezier segments specified by aulSegments.
</syntaxhighlight>

===Constructing with cBezier===
If the cSpline should be populated with one or more existing bezier curves, one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline(cBezier aSegmentsArray) // Takes an existing cBezier array and uses that to populate the new spline.
cSpline(cBezier@ ahBezier) // Uses a reference to an existing cBezier to populate the new spline with a single segment.
</syntaxhighlight>

===Constructing with cVector===
Finally, if the cSpline should be populated a curve or line defined by cVector arguments, one of these constructors will help:
<syntaxhighlight lang="cpp">
cSpline(cVector avStart, cVector avCtrlStart, cVector avCtrlEnd, cVector avEnd)
// Takes four vector positions and builds a cubic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avCtrl, cVector avEnd)
// Takes three vector positions and builds a approximation of a quadratic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avEnd)
// Takes two vector positions and populate the new spline with a single segment in the form of a straight line between two points.
</syntaxhighlight>

==Methods==
cBezier provides the following methods:

====AddSegment()====
<syntaxhighlight lang="cpp">
bool AddSegment(cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Appends a bezier onto the spline as new segment. Returns false if the spline is already full, or true if it was successfully added.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment will be adjusted to connect to the start point and entrance tangent of the new one.
#''cBezier ahSegment'' - A bezier to be appended to the spline.
#''bool abSnap'' - Whether to adjust the previous segment to connect to the new one. (Optional, default = true)

====UpdateSegment()====
<syntaxhighlight lang="cpp">
bool UpdateSegment(uint aulIndex, cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Updates an existing segment by index, replacing it with a new bezier. Returns false if the segment does not already exist, or true if it was successfully updated.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment, and the start point and entrance tangent of the next segment will be adjusted to connect to the updated segment.
#''uint aulIndex'' - The index of the segment to be replaced.
#''cBezier ahSegment'' - A bezier to be replace the bezier at the given index. to the spline.
#''bool abSnap'' - Whether to adjust the previous and next segments to connect to the updated one. (Optional, default = true)

====AddPoint()====
<syntaxhighlight lang="cpp">
bool AddPoint(bool abLast = false, cVector avNextPosition, cVector avNextTangent)
bool AddPoint(bool abLast = false, cVector avNextPosition)
</syntaxhighlight>
Appends a position to the end of the spline. Returns false if the spline is already full, or true if it was successfully added.
 avNextTangent is optional and can be omitted. It specifies the tangent as the velocity (direction and scale) of the spline at the new point. If omitted, no tangent is used at this time, but once you have finished adding points, abLast = true should be used and automatic tangents will be applied at that time.
 The automatic tangents are only applied to points where no tangent was given, and only once the spine is marked as "finished" by using abLast = true;
#''bool abLast'' - Whether this is the last point to be added. (Optional, default = false)
#''cVector avNextPosition'' - A position in space to add to the spline.
#''cVector avNextTangent'' - The forward velocity of the spline as it passes through the new position. (Optional, default = auto)

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMySpline.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the spline.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMySpline.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the spline at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the entire spline.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a string describing the spline, including the x,y,z components of its start and end points, and the number of segments.

__FORCETOC__

HPL2/HPL2 Helper Scripts/String

2024-02-11T02:16:02Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_String.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_String.hps" provides some extended maths functionality for modders. The new String class contains additional string functions, including replacement, sequence generation and more.

Despite the name, this is not a string class itself, and does not contain text or replace the "string" type. String should be used similarly to Math, as a library of functions. For example:
<syntaxhighlight lang="cpp">
string welcomeText = "I bid you welcome to my cabinet of perturbation.";
string cabinetType = "liquor";
welcomeText = String.ReplaceAll(welcomeText, "perturbation", cabinetType);
</syntaxhighlight>

"HelperScripts_String.hps" also defines the Str class. The Str class is intended to provide something like a template parameter, or a loosely typed variable, for string formatting.

=String=

==Behaviours==
"HelperScripts_String.hps" script declares an object called '''String''', of the new script class cString. To access its methods, just use "String." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
String.Replace("catfish", "cat", "dog");
</syntaxhighlight>

==Properties==
String has no public properties.

==Methods==

===Length===
String provides the following methods for working with string sizes:

====IsEmpty()====
<syntaxhighlight lang="cpp">
bool IsEmpty(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns true if the string is empty ("").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check if empty.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
bool bA = String.IsEmpty(" ");
bool bB = String.IsEmpty(" ", trimAll);
// bA is assigned false. bB is assigned true, as the empty space is not counted.
</syntaxhighlight>

====Length()====
<syntaxhighlight lang="cpp">
uint Length(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns the number of characters in the string.
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. This is the same as asString.length(). With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check the length of.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example 1:
int lA = String.Length(" words words words ");
int lB = String.Length(" words words words ", trimEnd);
int lC = String.Length(" words words words ", trimAll);
// lA becomes 21, lB becomes 18 and lC becomes 17.

// Example 2:
while (sSleepy.Length() < 20) sSleepy += "z";
// The while loop continues until the string is at least 20 characters long.
</syntaxhighlight>

====Trim()====
<syntaxhighlight lang="cpp">
string Trim(string &in asString, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Removes whitespace and control characters from the beginning and end of a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the string will not be trimmed. With trimStart, whitespace and control characters will be removed from the start of the string. With trimEnd, whitespace and control characters will be removed from the end of the string. With trimAll (default), whitespace and control characters will be removed from both ends of the string.
#''string asString'' - The string to trim.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
string sSpooky = " sppoooky ";
sSpooky = String.Trim(aSpooky, trimStart);
// The initial spaces have been removed. sSpooky now equals "sppoooky ".
sSpooky = String.Trim(aSpooky);
// Now the trailing spaces have been removed too. sSpooky now equals "spoooky".
</syntaxhighlight>

===Parsing===
String provides the following methods for parsing strings:

====ToInt()====
<syntaxhighlight lang="cpp">
int ToInt(string asString)
</syntaxhighlight>
If possible, returns an integer converted from a string, else returns 0. This is the same as the normal global function StringToInt(), but is included here for consistency.

====ToFloat()====
<syntaxhighlight lang="cpp">
float ToFloat(string asString)
</syntaxhighlight>
If possible, returns a float converted from a string, else returns 0.0f. This is the same as the normal global function StringToFloat(), but is included here for consistency.

====ToBool()====
<syntaxhighlight lang="cpp">
bool ToBool(string asString)
</syntaxhighlight>
If possible, returns a boolean converted from a string, else returns false. This is the same as the normal global function StringToBool(), but is included here for consistency.

===Characters===
String provides the following miscellaneous methods for working with character codes:

====CharToString()====
<syntaxhighlight lang="cpp">
string CharToString(uint8 auiChar)
</syntaxhighlight>
Given an ASCII character code, this returns a string containing that single character. (Only works with ASCII, not full Unicode.)
#''uint8 auiChar'' - An ASCII character code to be converted to a string.
<syntaxhighlight lang="cpp">
// Example 1:
string sSymbols = String.CharToString(126) + String.CharToString(64) + String.CharToString(63);
// sSymbols now says "~@?".
</syntaxhighlight>

====StringToChar()====
<syntaxhighlight lang="cpp">
uint8 StringToChar(string asSingleChar)
</syntaxhighlight>
Given a single character string, this returns that character as an ASCII code. If the string is empty then 0 is returned (null character). If the string is longer than one character, the rest are ignored. (Only works with ASCII, not full Unicode.)
#''string asSingleChar'' - A string containing a character to be converted to a character code.
<syntaxhighlight lang="cpp">
// Example:
uint8 uiCharacter = String.StringToChar(sSomeText);
if (uiCharacter >= 48 && ul8Character <= 57) DoStuff();
// The condition succeeds if the first character of sSomeText is a numeric digit (ASCII codes 48-57).
</syntaxhighlight>

====CharArrayToString()====
<syntaxhighlight lang="cpp">
string CharArrayToString(uint8[] ausCharArray, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given an array of ASCII codes, this returns those character joined into a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the array will be included. With trimStart, any whitespace or control characters at the start of the array will be excluded. With trimEnd, any whitespace or control characters at the end of the array will be excluded. With trimAll, any whitespace or control characters at either end of the array will be excluded.
#''uint8[] ausCharArray'' - An array of ASCII character codes (unsigned 8bit ints), to be joined.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
See StringToCharArray() for an example. 

====StringToCharArray()====
<syntaxhighlight lang="cpp">
uint8[] StringToCharArray(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given a string, this splits the string and returns it as an array of ASCII codes. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the string will be included. With trimStart, any whitespace or control characters at the start of the string will be excluded. With trimEnd, any whitespace or control characters at the end of the string will be excluded. With trimAll, any whitespace or control characters at either end of the string will be excluded.
#''string asString'' - A string to be split.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
string Rot13(string asInput)
{
uint8[] chars = String.StringToCharArray(asInput, trimAll);
for (uint i = 0; i < chars.length(); i++)
{
if (chars[i] >= 65 && chars[i] <= 90 || chars[i] >= 141 && chars[i] <= 172)
{
chars[i] += 13;
if (chars[i] > 90 && chars[i] < 141 || chars[i] > 172)
{
chars[i] -= 26;
}
}
}
return String.CharArrayToString(chars );
}
// This example is a whole Rot13 function. The string arg asInput is broken into an array of chars. Any char that is a upper or lower case alphabet letter is moved 13 characters. Then the char array is made back into a string and returned.
</syntaxhighlight>

===Case===
String provides the following methods for changing the case of a string:

====ToUpper()====
<syntaxhighlight lang="cpp">
string ToUpper(string asString)
uint8 ToUpper(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as upper case. If any character is a lower case letter, it will be swapped for upper case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to upper case.
<syntaxhighlight lang="cpp">
// Example 1:
string sUpper = String.ToUpper("Dark Descent");
// sUpper is assigned "DARK DESCENT".

// Example 2:
if (String.ToUpper(sSomeTextA) == String.ToUpper(sSomeTextB))
// The condition succeeds if sSomeTextA and sSomeTextB are equal, regardless of their capitalisation.
</syntaxhighlight>

====ToLower()====
<syntaxhighlight lang="cpp">
string ToLower(string asString)
uint8 ToLower(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as lower case. If any character is a upper case letter, it will be swapped for lower case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to lower case.
<syntaxhighlight lang="cpp">
// Example:
string sLower = String.ToLower("Dark Descent");
// sLower is assigned "dark descent".
</syntaxhighlight>

===Searching===
String provides the following methods for changing the case of a string:

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(string asString, string asSubString)
</syntaxhighlight>
Returns true if asSubString can be found in asString. This is the same as the normal global function StringContains(), but is included in String for consistency.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
<syntaxhighlight lang="cpp">
// Example:
if (String.Contains(sCurrentObjective, "thalers");
// The condition succeeds if the string sCurrentObjective contains the substring "thalers".
</syntaxhighlight>

====Find()====
<syntaxhighlight lang="cpp">
int Find(string asString, string asSubString, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches for a substring within a string, and the returns the index of the first character of the first instance of the substring.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
int lA = String.Find("Grunt", "run");
int lB = String.Find("Agrippa", "RIP", caseInsensitive);
int lC = String.Find("Herbert", "er");
int lD = String.Find("Herbert", "er", dirFromEnd);
// lA is assigned 1. lB is assigned 2.
// lC is assigned 1, but searching from the end lD is assigned 4.
</syntaxhighlight>

====NearlyEqual()====
<syntaxhighlight lang="cpp">
bool NearlyEqual(string asA, string asB, uint aulErrors = 0, enumStringCase aCaseOption = caseInsensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Compares two strings and returns true if they are the almost identical, with options for ignoring case and/or leading and trailing whitespace.
 The argument aulErrors defines how many characters are allowed to be different for the strings to considered "nearly equal". If omitted, zero errors are allowed. Errors are counted 'after' any trimming takes place.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the string will not be trimmed. With trimStart, whitespace and control characters will be removed from the start of the string. With trimEnd, whitespace and control characters will be removed from the end of the string. With trimAll (default), whitespace and control characters will be removed from both ends of the string.
#''string asA'' - The first string to compare.
#''string asB'' - The second string to compare.
#''uint aulErrors'' - How many characters are allowed to not match, after trimming. (Optional, default = 0)
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
if (asPasswordGuess == sPasswordAnswer) OpenDoor();
else if (String.NearlyEqual(asPasswordGuess, sPasswordAnswer, 1, caseInsensitive)) GiveHint();
</syntaxhighlight>

===Substrings===
String provides the following methods for working with parts of strings:

====Sub()====
<syntaxhighlight lang="cpp">
string Sub(string asString, uint aulStart, uint aulCount)
string Sub(string asString, uint aulStart)
</syntaxhighlight>
Returns part of a string. This is the same as the normal global function StringSub(), except that aulCount can be omitted. If aulCount is specified, the substring returned starts at aulStart and proceeds for aulCount characters. If aulCount is omitted then the substring starts at aulStart and proceeds to the end of the original string.
#''string asString'' - The string to get the substring from.
#''uint aulStart'' - The index of the character that is the start of the substring.
#''uint aulCount'' - The number of characters in the substring. (Optional, default = the remaining length of the string)
<syntaxhighlight lang="cpp">
// Example:
string sA = String.Sub("grunt", 1, 3);
string sB = String.Sub("grunt", 1);
// sA is assigned "run". sB is assigned "runt".
</syntaxhighlight>

====Replace()====
<syntaxhighlight lang="cpp">
string Replace(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches through a string and if it finds an instance of a given substring, it replaces it with another. Replace() replaces the first instance found. To replace all instances, consider ReplaceAll().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.Replace(sMyStringA, "cat", "dog");
string sMyStringC = String.Replace(sMyStringA, "cat", "dog", dirFromEnd);
// sMyStringB becomes "dogfish catfood". sMyStringC becomes "catfish dogfood".
</syntaxhighlight>

====ReplaceAll()====
<syntaxhighlight lang="cpp">
string ReplaceAll(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive)
</syntaxhighlight>
Searches through a string and replaces all instances of a substring with another. To avoid an infinite loop, asReplace can't contain a match to asFind it would. Consider using Replace() instead.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.ReplaceAll(sMyStringA, "cat", "dog");
// sMyStringB becomes "dogfish dogfood".
</syntaxhighlight>

====Format()====
<syntaxhighlight lang="cpp">
string Format(string asString, Str[] argArray)
string Format(string asString, Str arg0, Str arg1, ... Str arg7)
</syntaxhighlight>
A minimal version of the string formatting methods found in other languages. It doesn't provide number formating options, but it does allow an arbirtrary number of variables to be inserted into a string, regardless of data type, using the Str class. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. This is the method used by the cDebug class.
 Format() returns a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero. If an argument is supplied but the text doesn't contain a corresponding token, then the argument won't be included. If the text contains a token but not corresponding argument is supplied, then the token will remain in the output text.
 Up to eight individual Str arguments can be provides, or an array of Str. (Unfortunately, anonymous arrays as arguments are not supported, so the array must be declared.)
#''string asString'' - A template string containing tokens ("{i}") to be replaced by the other arguments.
#''argArray or arg0'' - An array of Str instances, or a single Str instance, to replace tokens in the string.
#''arg1 - arg7'' - If not using an array, an additional 7 single Str arguments can be optionally given.
<syntaxhighlight lang="cpp">
// Example 1:
string sNewString = String.Format("I got {0} problems but this script ain't {1}.", Str(99), Str("one"));
// sNewString is assigned "I got 99 problems but this script ain't one."

// Example 2:
Str[] myArray = { Str("Daniel"), Str("London"), Str("Mayfair") };
string myOutput = String.Format("My name is {0}, I live in {1} at... at... {2}...", myArray);
// myOutput becomes "My name is Daniel, I live in London at... at... Mayfair..."
</syntaxhighlight>

===Arrays and lists===
String provides the following methods for splitting and joining collections of strings:

====Join()====
<syntaxhighlight lang="cpp">
string Join(string[] asStringArray, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
string Join(cListBase asGenericList, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a collection of strings, this returns them joined into a single string. The collection can be a string array (string[]), a list of strings (cListString), or any type other type of list. (The ToStringArray() method of the cListBase class is used, which in turn calls the ToString() method of each node. For most list classes this will return valid strings, but if the instanced list is itself cListBase or cListGeneric, empty strings will be returned.)
 Optionally, a separator string can be included, which will be inserted between each item. If omitted, asSeparator defaults to "" - i.e., no separator. Example uses could be " " or "_".
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the strings in the array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings before they are joined. With trimEnd, whitespace will be removed from the end of the strings before they are joined. With trimAll (default), whiltespace will be removed from both ends of the strings before they are joined. Additionally any empty strings will be ignored unless trimNone is used.
#''string[] asStringArray, cListString asListString'' - An array of strings, a list of strings, or any other list type that can output strings, to be joined.
#''stromg asSeparator'' - A substring to insert between each joined string. (Optional, default = "")
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example 1:
float[] fNumbers = { 2.33f, 3.44f, 4.55f, 5.66f };
string sNumberText = String.Join(fNumbers, " >> ");
// sNumberText will read "2.33 >> 3.44 >> 4.55 >> 5.66".

// Example 2:
cListString sJumble = String.Join(String.SplitToList("The Inner Sanctum, my most precious chamber, Daniel.").Shuffle(), " ");
// sJumble becomes the words of the string, in a random order. First the string is split into a list of strings, the list's Shuffle() method is called, and the result is passed to Join().
</syntaxhighlight>

====SplitToList()====
<syntaxhighlight lang="cpp">
cListString SplitToList(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into a list of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned list contains the individual words in the string.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting list will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting list. With trimEnd, whitespace will be removed from the end of the strings in the resulting list. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
#''string asString'' - A string to be split into a list.
#''string asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
cListString myListA = String.SplitToList("cat_dog_catfish_dogfish", "_");
cListString myListB = String.SplitToList("cat_dog_catfish_dogfish", "_Dog");
cListString myListC = String.SplitToList("cat_dog_catfish_dogfish", "_Dog", caseInsensitive);
// myListA is created with the items "cat", "dog", "catfish" and "dogfish".
// myListB is created with the no items, as the delimiter is not found with the defaul caseSensitive option.
// myListC is created with the items "cat", "_catfish" and "fish".
</syntaxhighlight>

====SplitToArray()====
<syntaxhighlight lang="cpp">
string[] SplitToArray(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into an array of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned array contains the individual words in the string. Consider also: SplitToList().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the delimiter must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting array. With trimEnd, whitespace will be removed from the end of the strings in the resulting array. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
 (The max length of the array is 256, but advanced users could edit that if needed.)
#''string asString'' - A string to be split into an array.
#''asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
For an example, see SplitToList() 

===Sequences===
String provides the following methods for working with numbered string sequences:

====StringRange()====
<syntaxhighlight lang="cpp">
string[] StringRange(string asPrefix, uint alRangeFirst, uint alRangeLast, string asSuffix)
string[] StringRange(string asPrefix, string asRangeFirst, string asRangeLast, string asSuffix)
</syntaxhighlight>
Returns an array of strings where each string in the array is made up of a prefix, followed by an iterator from given range, and then a suffix. The prefix and/or suffix can be "".
 Accepts the iterator range as either integers or characters, expressed as an inclusive min and inclusive max. Any integers or any ASCII characters could be used, as long as the min/first is less than the max/last.
#''string asPrefix'' - A string to add at the start of the output strings.
#''int alRangeFirst, string asRangeFirst'' - An integer or a single character string for the start of the iteration. (inclusive).
#''int alRangeLast, string asRangeLast'' - An integer or a single character string for the end of the interation (inclusive).
#''string asSuffix'' - A string to add at the end of the output strings.
<syntaxhighlight lang="cpp">
// Example 1:
string[] sDoorNames = String.StringRange("door", 2, 5);
for (uint i = 0; i < sDoorNames.length(); i++) SetSwingDoorLocked(sDoorNames, true, true);
// Creates an array of strings containing "door2", "door3", "door4" and "door5", and passes each of them to SetSwingDoorLocked().

// Example 2:
string[] sStuffAndJunk = StringRange("stuff_", "A", "C", "_andJunk");
// sStuffAndJunk is assigned with the strings "stuff_A_andJunk", "stuff_B_andJunk" and "stuff_C_andJunk".
</syntaxhighlight>

====IntToStringFixedDigits()====
<syntaxhighlight lang="cpp">
string IntToStringFixedDigits(uint aulNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
string IntToStringFixedDigits(int alNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
</syntaxhighlight>
Returns a string representing an unsigned or positive int, with the specified number of characters, adding leading zeros if needed. aulNumber is the number to convert. auiDigits is the number of digits. E.g. 42 as 3 digits returns the string "042". auiDigits is an unsigned 8-bit int (0-255), because the max uint is only 10 digits. (Hey, if you want to try any make a string that's 2^32 followed by 245 zeros, that's none of my business!)
 aLimitOption is optional and can be omitted, or it can be limitFree, limitClamped or limitWrapped. With limitFree, the number is not clamped, so auiDigits is a minimum. E.g. 1 as 2 digits returns "01" but 123 as 2 digits returns "123". With limitClamped (default), the number will be clamped within the range of the digits. E.g. 123 as 2 digits returns "99". With limitWrapped, the number will be modulated. E.g. 123 as 2 digits returns "23".
#''uint aulNumber, int alNumber' - An unsigned integer to be respresented in the string. If the supplied int is signed and less than zero, it will be treated as zero.
#''uint8 auiDigits'' - The min number of digits to include in the string.
#''enumLimitType aLimitOption'' - Can be limitFree, limitClamped or limitWrapped. (Optional, default = limitClamped)
<syntaxhighlight lang="cpp">
// Example 1:
string sNum = String.IntToStringFixedDigits(1188, 4, limitWrapped);
// sNum becomes "0088".

// Example 2:
for (uint i = 1; i <= 12; i++) SetSwingDoorLocked("door_" + String.IntToStringFixedDigits(i, 3), true, true);
// This example imagines that the level has 12 doors named in the style "door_001", "door_002", ... "door_009", "door_010", "door_011", "door_012".
</syntaxhighlight>

=Str class=
The Str class is used in the String.Format() and Debug.Message() methods.
 It's purpose is to provide something like a template parameter, or a loosely typed variable, for string formatting. The main goal is just to let modders pass values for string formatting without requiring hundreds of overloads. It's definitely clunkier in debug mode, but outside of debug mode it's more efficient.

==Behaviours==
The Str constructors can be passed a reference to a single string, int, uint, float, double, bool, cVector, cRotator, cPoint, cBezier, cSpline, or a list type.
<syntaxhighlight lang="cpp">
// Example:
Str(3)
Str(myInt)
Str(myVector)
</syntaxhighlight>

==Properties==
Str has no public properties.

==Methods==
The only method is the ToString() function:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the stored variable as a string.
<syntaxhighlight lang="cpp">
// Example 1:
Debug.Message(3, "Created new rotator {0} for puzzle #{1}.", Str(myRotator), Str(myInt));

// Example 2:
SetLevelDoorLockedText("BigDoor", "BigDoorMessages", String.Format("Door_Zone{0}_Type{1}", Str(doorZone), Str(doorType)));
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/String

2024-02-11T02:14:22Z

Mrbehemo: Added NearlyEqual()

{{TocRight}}
This page documents "HelperScripts_String.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_String.hps" provides some extended maths functionality for modders. The new String class contains additional string functions, including replacement, sequence generation and more.

Despite the name, this is not a string class itself, and does not contain text or replace the "string" type. String should be used similarly to Math, as a library of functions. For example:
<syntaxhighlight lang="cpp">
string welcomeText = "I bid you welcome to my cabinet of perturbation.";
string cabinetType = "liquor";
welcomeText = String.ReplaceAll(welcomeText, "perturbation", cabinetType);
</syntaxhighlight>

"HelperScripts_String.hps" also defines the Str class. The Str class is intended to provide something like a template parameter, or a loosely typed variable, for string formatting.

=String=

==Behaviours==
"HelperScripts_String.hps" script declares an object called '''String''', of the new script class cString. To access its methods, just use "String." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
String.Replace("catfish", "cat", "dog");
</syntaxhighlight>

==Properties==
String has no public properties.

==Methods==

===Length===
String provides the following methods for working with string sizes:

====IsEmpty()====
<syntaxhighlight lang="cpp">
bool IsEmpty(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns true if the string is empty ("").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check if empty.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
bool bA = String.IsEmpty(" ");
bool bB = String.IsEmpty(" ", trimAll);
// bA is assigned false. bB is assigned true, as the empty space is not counted.
</syntaxhighlight>

====Length()====
<syntaxhighlight lang="cpp">
uint Length(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns the number of characters in the string.
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. This is the same as asString.length(). With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check the length of.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example 1:
int lA = String.Length(" words words words ");
int lB = String.Length(" words words words ", trimEnd);
int lC = String.Length(" words words words ", trimAll);
// lA becomes 21, lB becomes 18 and lC becomes 17.

// Example 2:
while (sSleepy.Length() < 20) sSleepy += "z";
// The while loop continues until the string is at least 20 characters long.
</syntaxhighlight>

====NearlyEqual()====
<syntaxhighlight lang="cpp">
bool NearlyEqual(string asA, string asB, uint aulErrors = 0, enumStringCase aCaseOption = caseInsensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Compares two strings and returns true if they are the almost identical, with options for ignoring case and/or leading and trailing whitespace.
 The argument aulErrors defines how many characters are allowed to be different for the strings to considered "nearly equal". If omitted, zero errors are allowed. Errors are counted 'after' any trimming takes place.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the string will not be trimmed. With trimStart, whitespace and control characters will be removed from the start of the string. With trimEnd, whitespace and control characters will be removed from the end of the string. With trimAll (default), whitespace and control characters will be removed from both ends of the string.
#''string asA'' - The first string to compare.
#''string asB'' - The second string to compare.
#''uint aulErrors'' - How many characters are allowed to not match, after trimming. (Optional, default = 0)
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
if (asPasswordGuess == sPasswordAnswer) OpenDoor();
else if (String.NearlyEqual(asPasswordGuess, sPasswordAnswer, 1, caseInsensitive)) GiveHint();
</syntaxhighlight>

====Trim()====
<syntaxhighlight lang="cpp">
string Trim(string &in asString, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Removes whitespace and control characters from the beginning and end of a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the string will not be trimmed. With trimStart, whitespace and control characters will be removed from the start of the string. With trimEnd, whitespace and control characters will be removed from the end of the string. With trimAll (default), whitespace and control characters will be removed from both ends of the string.
#''string asString'' - The string to trim.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
string sSpooky = " sppoooky ";
sSpooky = String.Trim(aSpooky, trimStart);
// The initial spaces have been removed. sSpooky now equals "sppoooky ".
sSpooky = String.Trim(aSpooky);
// Now the trailing spaces have been removed too. sSpooky now equals "spoooky".
</syntaxhighlight>

===Parsing===
String provides the following methods for parsing strings:

====ToInt()====
<syntaxhighlight lang="cpp">
int ToInt(string asString)
</syntaxhighlight>
If possible, returns an integer converted from a string, else returns 0. This is the same as the normal global function StringToInt(), but is included here for consistency.

====ToFloat()====
<syntaxhighlight lang="cpp">
float ToFloat(string asString)
</syntaxhighlight>
If possible, returns a float converted from a string, else returns 0.0f. This is the same as the normal global function StringToFloat(), but is included here for consistency.

====ToBool()====
<syntaxhighlight lang="cpp">
bool ToBool(string asString)
</syntaxhighlight>
If possible, returns a boolean converted from a string, else returns false. This is the same as the normal global function StringToBool(), but is included here for consistency.

===Characters===
String provides the following miscellaneous methods for working with character codes:

====CharToString()====
<syntaxhighlight lang="cpp">
string CharToString(uint8 auiChar)
</syntaxhighlight>
Given an ASCII character code, this returns a string containing that single character. (Only works with ASCII, not full Unicode.)
#''uint8 auiChar'' - An ASCII character code to be converted to a string.
<syntaxhighlight lang="cpp">
// Example 1:
string sSymbols = String.CharToString(126) + String.CharToString(64) + String.CharToString(63);
// sSymbols now says "~@?".
</syntaxhighlight>

====StringToChar()====
<syntaxhighlight lang="cpp">
uint8 StringToChar(string asSingleChar)
</syntaxhighlight>
Given a single character string, this returns that character as an ASCII code. If the string is empty then 0 is returned (null character). If the string is longer than one character, the rest are ignored. (Only works with ASCII, not full Unicode.)
#''string asSingleChar'' - A string containing a character to be converted to a character code.
<syntaxhighlight lang="cpp">
// Example:
uint8 uiCharacter = String.StringToChar(sSomeText);
if (uiCharacter >= 48 && ul8Character <= 57) DoStuff();
// The condition succeeds if the first character of sSomeText is a numeric digit (ASCII codes 48-57).
</syntaxhighlight>

====CharArrayToString()====
<syntaxhighlight lang="cpp">
string CharArrayToString(uint8[] ausCharArray, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given an array of ASCII codes, this returns those character joined into a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the array will be included. With trimStart, any whitespace or control characters at the start of the array will be excluded. With trimEnd, any whitespace or control characters at the end of the array will be excluded. With trimAll, any whitespace or control characters at either end of the array will be excluded.
#''uint8[] ausCharArray'' - An array of ASCII character codes (unsigned 8bit ints), to be joined.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
See StringToCharArray() for an example. 

====StringToCharArray()====
<syntaxhighlight lang="cpp">
uint8[] StringToCharArray(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given a string, this splits the string and returns it as an array of ASCII codes. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the string will be included. With trimStart, any whitespace or control characters at the start of the string will be excluded. With trimEnd, any whitespace or control characters at the end of the string will be excluded. With trimAll, any whitespace or control characters at either end of the string will be excluded.
#''string asString'' - A string to be split.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
string Rot13(string asInput)
{
uint8[] chars = String.StringToCharArray(asInput, trimAll);
for (uint i = 0; i < chars.length(); i++)
{
if (chars[i] >= 65 && chars[i] <= 90 || chars[i] >= 141 && chars[i] <= 172)
{
chars[i] += 13;
if (chars[i] > 90 && chars[i] < 141 || chars[i] > 172)
{
chars[i] -= 26;
}
}
}
return String.CharArrayToString(chars );
}
// This example is a whole Rot13 function. The string arg asInput is broken into an array of chars. Any char that is a upper or lower case alphabet letter is moved 13 characters. Then the char array is made back into a string and returned.
</syntaxhighlight>

===Case===
String provides the following methods for changing the case of a string:

====ToUpper()====
<syntaxhighlight lang="cpp">
string ToUpper(string asString)
uint8 ToUpper(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as upper case. If any character is a lower case letter, it will be swapped for upper case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to upper case.
<syntaxhighlight lang="cpp">
// Example 1:
string sUpper = String.ToUpper("Dark Descent");
// sUpper is assigned "DARK DESCENT".

// Example 2:
if (String.ToUpper(sSomeTextA) == String.ToUpper(sSomeTextB))
// The condition succeeds if sSomeTextA and sSomeTextB are equal, regardless of their capitalisation.
</syntaxhighlight>

====ToLower()====
<syntaxhighlight lang="cpp">
string ToLower(string asString)
uint8 ToLower(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as lower case. If any character is a upper case letter, it will be swapped for lower case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to lower case.
<syntaxhighlight lang="cpp">
// Example:
string sLower = String.ToLower("Dark Descent");
// sLower is assigned "dark descent".
</syntaxhighlight>

===Searching===
String provides the following methods for changing the case of a string:

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(string asString, string asSubString)
</syntaxhighlight>
Returns true if asSubString can be found in asString. This is the same as the normal global function StringContains(), but is included in String for consistency.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
<syntaxhighlight lang="cpp">
// Example:
if (String.Contains(sCurrentObjective, "thalers");
// The condition succeeds if the string sCurrentObjective contains the substring "thalers".
</syntaxhighlight>

====Find()====
<syntaxhighlight lang="cpp">
int Find(string asString, string asSubString, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches for a substring within a string, and the returns the index of the first character of the first instance of the substring.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
int lA = String.Find("Grunt", "run");
int lB = String.Find("Agrippa", "RIP", caseInsensitive);
int lC = String.Find("Herbert", "er");
int lD = String.Find("Herbert", "er", dirFromEnd);
// lA is assigned 1. lB is assigned 2.
// lC is assigned 1, but searching from the end lD is assigned 4.
</syntaxhighlight>

===Substrings===
String provides the following methods for working with parts of strings:

====Sub()====
<syntaxhighlight lang="cpp">
string Sub(string asString, uint aulStart, uint aulCount)
string Sub(string asString, uint aulStart)
</syntaxhighlight>
Returns part of a string. This is the same as the normal global function StringSub(), except that aulCount can be omitted. If aulCount is specified, the substring returned starts at aulStart and proceeds for aulCount characters. If aulCount is omitted then the substring starts at aulStart and proceeds to the end of the original string.
#''string asString'' - The string to get the substring from.
#''uint aulStart'' - The index of the character that is the start of the substring.
#''uint aulCount'' - The number of characters in the substring. (Optional, default = the remaining length of the string)
<syntaxhighlight lang="cpp">
// Example:
string sA = String.Sub("grunt", 1, 3);
string sB = String.Sub("grunt", 1);
// sA is assigned "run". sB is assigned "runt".
</syntaxhighlight>

====Replace()====
<syntaxhighlight lang="cpp">
string Replace(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches through a string and if it finds an instance of a given substring, it replaces it with another. Replace() replaces the first instance found. To replace all instances, consider ReplaceAll().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.Replace(sMyStringA, "cat", "dog");
string sMyStringC = String.Replace(sMyStringA, "cat", "dog", dirFromEnd);
// sMyStringB becomes "dogfish catfood". sMyStringC becomes "catfish dogfood".
</syntaxhighlight>

====ReplaceAll()====
<syntaxhighlight lang="cpp">
string ReplaceAll(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive)
</syntaxhighlight>
Searches through a string and replaces all instances of a substring with another. To avoid an infinite loop, asReplace can't contain a match to asFind it would. Consider using Replace() instead.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.ReplaceAll(sMyStringA, "cat", "dog");
// sMyStringB becomes "dogfish dogfood".
</syntaxhighlight>

====Format()====
<syntaxhighlight lang="cpp">
string Format(string asString, Str[] argArray)
string Format(string asString, Str arg0, Str arg1, ... Str arg7)
</syntaxhighlight>
A minimal version of the string formatting methods found in other languages. It doesn't provide number formating options, but it does allow an arbirtrary number of variables to be inserted into a string, regardless of data type, using the Str class. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. This is the method used by the cDebug class.
 Format() returns a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero. If an argument is supplied but the text doesn't contain a corresponding token, then the argument won't be included. If the text contains a token but not corresponding argument is supplied, then the token will remain in the output text.
 Up to eight individual Str arguments can be provides, or an array of Str. (Unfortunately, anonymous arrays as arguments are not supported, so the array must be declared.)
#''string asString'' - A template string containing tokens ("{i}") to be replaced by the other arguments.
#''argArray or arg0'' - An array of Str instances, or a single Str instance, to replace tokens in the string.
#''arg1 - arg7'' - If not using an array, an additional 7 single Str arguments can be optionally given.
<syntaxhighlight lang="cpp">
// Example 1:
string sNewString = String.Format("I got {0} problems but this script ain't {1}.", Str(99), Str("one"));
// sNewString is assigned "I got 99 problems but this script ain't one."

// Example 2:
Str[] myArray = { Str("Daniel"), Str("London"), Str("Mayfair") };
string myOutput = String.Format("My name is {0}, I live in {1} at... at... {2}...", myArray);
// myOutput becomes "My name is Daniel, I live in London at... at... Mayfair..."
</syntaxhighlight>

===Arrays and lists===
String provides the following methods for splitting and joining collections of strings:

====Join()====
<syntaxhighlight lang="cpp">
string Join(string[] asStringArray, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
string Join(cListBase asGenericList, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a collection of strings, this returns them joined into a single string. The collection can be a string array (string[]), a list of strings (cListString), or any type other type of list. (The ToStringArray() method of the cListBase class is used, which in turn calls the ToString() method of each node. For most list classes this will return valid strings, but if the instanced list is itself cListBase or cListGeneric, empty strings will be returned.)
 Optionally, a separator string can be included, which will be inserted between each item. If omitted, asSeparator defaults to "" - i.e., no separator. Example uses could be " " or "_".
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the strings in the array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings before they are joined. With trimEnd, whitespace will be removed from the end of the strings before they are joined. With trimAll (default), whiltespace will be removed from both ends of the strings before they are joined. Additionally any empty strings will be ignored unless trimNone is used.
#''string[] asStringArray, cListString asListString'' - An array of strings, a list of strings, or any other list type that can output strings, to be joined.
#''stromg asSeparator'' - A substring to insert between each joined string. (Optional, default = "")
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example 1:
float[] fNumbers = { 2.33f, 3.44f, 4.55f, 5.66f };
string sNumberText = String.Join(fNumbers, " >> ");
// sNumberText will read "2.33 >> 3.44 >> 4.55 >> 5.66".

// Example 2:
cListString sJumble = String.Join(String.SplitToList("The Inner Sanctum, my most precious chamber, Daniel.").Shuffle(), " ");
// sJumble becomes the words of the string, in a random order. First the string is split into a list of strings, the list's Shuffle() method is called, and the result is passed to Join().
</syntaxhighlight>

====SplitToList()====
<syntaxhighlight lang="cpp">
cListString SplitToList(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into a list of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned list contains the individual words in the string.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting list will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting list. With trimEnd, whitespace will be removed from the end of the strings in the resulting list. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
#''string asString'' - A string to be split into a list.
#''string asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
cListString myListA = String.SplitToList("cat_dog_catfish_dogfish", "_");
cListString myListB = String.SplitToList("cat_dog_catfish_dogfish", "_Dog");
cListString myListC = String.SplitToList("cat_dog_catfish_dogfish", "_Dog", caseInsensitive);
// myListA is created with the items "cat", "dog", "catfish" and "dogfish".
// myListB is created with the no items, as the delimiter is not found with the defaul caseSensitive option.
// myListC is created with the items "cat", "_catfish" and "fish".
</syntaxhighlight>

====SplitToArray()====
<syntaxhighlight lang="cpp">
string[] SplitToArray(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into an array of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned array contains the individual words in the string. Consider also: SplitToList().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the delimiter must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting array. With trimEnd, whitespace will be removed from the end of the strings in the resulting array. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
 (The max length of the array is 256, but advanced users could edit that if needed.)
#''string asString'' - A string to be split into an array.
#''asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
For an example, see SplitToList() 

===Sequences===
String provides the following methods for working with numbered string sequences:

====StringRange()====
<syntaxhighlight lang="cpp">
string[] StringRange(string asPrefix, uint alRangeFirst, uint alRangeLast, string asSuffix)
string[] StringRange(string asPrefix, string asRangeFirst, string asRangeLast, string asSuffix)
</syntaxhighlight>
Returns an array of strings where each string in the array is made up of a prefix, followed by an iterator from given range, and then a suffix. The prefix and/or suffix can be "".
 Accepts the iterator range as either integers or characters, expressed as an inclusive min and inclusive max. Any integers or any ASCII characters could be used, as long as the min/first is less than the max/last.
#''string asPrefix'' - A string to add at the start of the output strings.
#''int alRangeFirst, string asRangeFirst'' - An integer or a single character string for the start of the iteration. (inclusive).
#''int alRangeLast, string asRangeLast'' - An integer or a single character string for the end of the interation (inclusive).
#''string asSuffix'' - A string to add at the end of the output strings.
<syntaxhighlight lang="cpp">
// Example 1:
string[] sDoorNames = String.StringRange("door", 2, 5);
for (uint i = 0; i < sDoorNames.length(); i++) SetSwingDoorLocked(sDoorNames, true, true);
// Creates an array of strings containing "door2", "door3", "door4" and "door5", and passes each of them to SetSwingDoorLocked().

// Example 2:
string[] sStuffAndJunk = StringRange("stuff_", "A", "C", "_andJunk");
// sStuffAndJunk is assigned with the strings "stuff_A_andJunk", "stuff_B_andJunk" and "stuff_C_andJunk".
</syntaxhighlight>

====IntToStringFixedDigits()====
<syntaxhighlight lang="cpp">
string IntToStringFixedDigits(uint aulNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
string IntToStringFixedDigits(int alNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
</syntaxhighlight>
Returns a string representing an unsigned or positive int, with the specified number of characters, adding leading zeros if needed. aulNumber is the number to convert. auiDigits is the number of digits. E.g. 42 as 3 digits returns the string "042". auiDigits is an unsigned 8-bit int (0-255), because the max uint is only 10 digits. (Hey, if you want to try any make a string that's 2^32 followed by 245 zeros, that's none of my business!)
 aLimitOption is optional and can be omitted, or it can be limitFree, limitClamped or limitWrapped. With limitFree, the number is not clamped, so auiDigits is a minimum. E.g. 1 as 2 digits returns "01" but 123 as 2 digits returns "123". With limitClamped (default), the number will be clamped within the range of the digits. E.g. 123 as 2 digits returns "99". With limitWrapped, the number will be modulated. E.g. 123 as 2 digits returns "23".
#''uint aulNumber, int alNumber' - An unsigned integer to be respresented in the string. If the supplied int is signed and less than zero, it will be treated as zero.
#''uint8 auiDigits'' - The min number of digits to include in the string.
#''enumLimitType aLimitOption'' - Can be limitFree, limitClamped or limitWrapped. (Optional, default = limitClamped)
<syntaxhighlight lang="cpp">
// Example 1:
string sNum = String.IntToStringFixedDigits(1188, 4, limitWrapped);
// sNum becomes "0088".

// Example 2:
for (uint i = 1; i <= 12; i++) SetSwingDoorLocked("door_" + String.IntToStringFixedDigits(i, 3), true, true);
// This example imagines that the level has 12 doors named in the style "door_001", "door_002", ... "door_009", "door_010", "door_011", "door_012".
</syntaxhighlight>

=Str class=
The Str class is used in the String.Format() and Debug.Message() methods.
 It's purpose is to provide something like a template parameter, or a loosely typed variable, for string formatting. The main goal is just to let modders pass values for string formatting without requiring hundreds of overloads. It's definitely clunkier in debug mode, but outside of debug mode it's more efficient.

==Behaviours==
The Str constructors can be passed a reference to a single string, int, uint, float, double, bool, cVector, cRotator, cPoint, cBezier, cSpline, or a list type.
<syntaxhighlight lang="cpp">
// Example:
Str(3)
Str(myInt)
Str(myVector)
</syntaxhighlight>

==Properties==
Str has no public properties.

==Methods==
The only method is the ToString() function:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the stored variable as a string.
<syntaxhighlight lang="cpp">
// Example 1:
Debug.Message(3, "Created new rotator {0} for puzzle #{1}.", Str(myRotator), Str(myInt));

// Example 2:
SetLevelDoorLockedText("BigDoor", "BigDoorMessages", String.Format("Door_Zone{0}_Type{1}", Str(doorZone), Str(doorType)));
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Math

2024-02-11T02:02:11Z

Mrbehemo: Added DistToEntity()

{{TocRight}}
This page documents "HelperScripts_Math.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Math.hps" provides some extended maths functionality for modders. The new Math class contains additional functions for a variety of purposes including interpolation, vectors, and more.

=Math=

==Behaviours==
"HelperScripts_Math.hps" script declares an object called '''Math''', of the new script class cDebug. To access its properties and methods, just use "Math." followed by the function call or property. E.g.:
<syntaxhighlight lang="cpp">
Math.Lerp(a, b, 0.75f);
x = Math.Pi;
</syntaxhighlight>

==Properties==
Math provides the following properties:

====Pi====
<syntaxhighlight lang="cpp">
float Pi
</syntaxhighlight>
The read-only property Pi returns Pi as a float.
<syntaxhighlight lang="cpp">
// Examples:
float fRightAngleRadians = Math.Pi / 2.0f;
float fOneEightyDegrees = Math.RadiansToDegrees(Math.Pi);
</syntaxhighlight>

====Tau====
<syntaxhighlight lang="cpp">
float Tau
</syntaxhighlight>
The read-only proerpty Tau returns Tau as a float. (Tau = 2*Pi)
<syntaxhighlight lang="cpp">
// Examples:
float fRightAngleRadians = Math.Tau / 4.0f;
float fThreeSixtyDegrees = Math.RadiansToDegrees(Math.Tau);
</syntaxhighlight>

==Methods==

===Arithmetic===
Math provides the following miscellaneous methods for working with numbers:

====Pow====
<syntaxhighlight lang="cpp">
float Pow(float afBase, float afExp)
int Pow(int alBase, uint aulExp)
uint Pow(uint aulBase, uint aulExp)
</syntaxhighlight>
Returns the base raised to the power the of exponent. This is the same as the normal global function MathPow(), except that it can also take an int or a uint.
<syntaxhighlight lang="cpp">
// Examples:
uint ulA = Math.Pow(9, 2);
float fB = Math.Pow(3.0f, 3.0f);
float fC = Math.Pow(3.0f, 1.0f/3.0f);
// ulA will become 81.
// fB will become 27. fC will become ~1.44225.
</syntaxhighlight>

====Sqrt====
<syntaxhighlight lang="cpp">
float Sqrt(float afX)
int Sqrt(int alX)
uint Sqrt(uint aulX)
</syntaxhighlight>
Returns the square root of the given number. This is the same as the normal global function MathSqrt(), except that it can also take an int or a uint, in which case the answer will be truncated.
<syntaxhighlight lang="cpp">
// Examples:
float fA = Math.Sqrt(2.0f);
int lB = Math.Sqrt(2);
// fA will become ~1.41421.
// lB will become 1.
</syntaxhighlight>

====NearlyEqual()====
<syntaxhighlight lang="cpp">
bool NearlyEqual(float afA, float afB, float afT = 0.00001f)
bool NearlyEqual(double adA, double adB, double adT = 0.00001)
bool NearlyEqual(cVector avA, cVector avB, float afT = 0.00001f)
</syntaxhighlight>
Returns true if A and B are equal within a tolerance of T. If omitted, afT defaults to 0.00001.
 Accepts either float, double, or cVector. For vectors, avA and avB must have the same number of dimensions, and each pair of dimensions must be nearly equal,
#''float afA, double adA, or cVector avA'' - The first value to compare.
#''float afB, double adB, or cVector avB'' - The second value to compare.
#''float afT, double afT'' - A tolerance with which to compare the values. '''(Optional, default = 0.00001)'''
<syntaxhighlight lang="cpp">
// Example:
if(Math.NearlyEqual(afScore, fTarget, 0.1f))
// The condition succeeds if the score is near to the target by 0.1.
</syntaxhighlight>

====SafeDivide()====
<syntaxhighlight lang="cpp">
float SafeDivide(float afA, float afB)
double SafeDivide(double adA, double adB)
int SafeDivide(int alA, int alB)
uint SafeDivide(uint aulA, uint aulB)
cVector SafeDivide(cVector avA, float afB)
cPoint SafeDivide(cPoint avA, float alB)
</syntaxhighlight>
Avoids divide by zero by checking for zeros first. If either value is zero, it just returns zero.
 Accepts a pair of numbers of the same type, or a vector and an appropriate number type.
#''float afA, double adA, int alA, uint aulA, cVector avA, or cPoint avA'' - The value to be divided.
#''float afB, double adB, int alB, or uint aulB'' - The value to be divided by.
<syntaxhighlight lang="cpp">
// Example:
int risky = 10 / Math.RandomInt(0, 3); // 1 in 3 chance of "divide by zero" error.
int safe = Math.SafeDivide(10, Math.RandomInt(0, 3)); // zero chance of "divide by zero" error.
</syntaxhighlight>

====DegreesToRadians()====
<syntaxhighlight lang="cpp">
float DegreesToRadians(float afD)
double DegreesToRadians(double adD)
</syntaxhighlight>
Converts degrees to radians and returns the result. (360 degrees is equal to 2*Pi radians.)
#''float afD, double adD'' - An angle in degrees, to be converted to radians.
<syntaxhighlight lang="cpp">
// Example:
if (Math.DegreesToRadians(fDeg) == Math.Pi / 2.0f) DoStuff();
// The condition will succeed if fDeg is 90.
</syntaxhighlight>

====RadiansToDegrees()====
<syntaxhighlight lang="cpp">
float RadiansToDegrees(float afD)
double RadiansToDegrees(double adD)
</syntaxhighlight>
Converts radians to degrees and returns the result. (360 degrees is equal to 2*Pi radians.)
#''float afD, double adD'' - An angle in radians, to be converted to degrees.
<syntaxhighlight lang="cpp">
// Example:
if (Math.DegreesToRadians(Math.Tau * fX) == 90) DoStuff();
// The condition will succeed if fX is 0.25f.
</syntaxhighlight>

====IsEven()====
<syntaxhighlight lang="cpp">
bool IsEven(int alX)
</syntaxhighlight>
Returns true if the given integer is an even number, or false if it is odd.
#''int alX'' - An int to check if even.
<syntaxhighlight lang="cpp">
// Example 1:
for (uint i = 0; i < 10; i++)
{
if (Math.IsEven(i)) DoStuff();
else DoOtherStuff();
}
// A different function is called depending on whether the loop counter is odd or even.

// Example 2:
int x = Math.RandomInt();
bool bEvenA = Math.IsEven(x);
bool bEvenB = x % 2 == 0;
// bEvenA and bEvenB are equal.
</syntaxhighlight>

====Sign()====
<syntaxhighlight lang="cpp">
int Sign(int alX)
uint Sign(float aulX)
float Sign(uint afX)
double Sign(double adX)
</syntaxhighlight>
Identifies whether a given number is positive, negative or zero, and returns the answer as either 1, -1 or 0.
#''int alX, uint aulX, float afX, or double adX'' - The number who's sign will be checked.
<syntaxhighlight lang="cpp">
// Example 1:
if (Math.Sign(fPrevious - fCurrent) == 1) sChange = "increased";
else if (Math.Sign(fPrevious - fCurrent) == -1) sChange = "decreased";
else sChange = "no change";
// Assuming fCurrent and fPrevious represent some value that is changing over time, this sets a string to represent that change.

// Example 2:
int lRando = Math.RandomInt(-50, -25);
bool bRandoIsNeg = Math.Sign(lRando) == -1;
// There is a roughly 1/3 chance that bRandoIsNeg will be true.
</syntaxhighlight>

====Abs()====
<syntaxhighlight lang="cpp">
float Abs(float afX)
double Abs(double adX)
int Abs(int alX)
uint Abs(uint aulX)
</syntaxhighlight>
Returns the absolute value of the number, ignoring it's sign. This is the same as the global function MathAbs(), except that it also takes an int, uint or double.
#''float afX, double adX, int alX, uint aulX'' - A postive or negative value, to be returned as absolute.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Abs(10);
int lB = Math.Abs(-10);
// lA and lB both become 10.
</syntaxhighlight>

====Min()====
<syntaxhighlight lang="cpp">
float Min(float afA, float afB)
double Min(double adA, double adB)
int Min(int alA, int alB)
uint Min(uint aulA, uint aulB)
</syntaxhighlight>
Compares two numbers and returns whichever one is the smaller value. This is the same as the global function MathMin(), except that it also takes an int, uint or double.
#''float afA, double adA, int alA, uint aulA'' - The first number to be compared.
#''float afB, double adB, int alB, uint aulB'' - The second number to be compared.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Min(10, lB);
// If lB is less than 10, lA will become equal to lB. Otherwise lA will become 10.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
float Max(float afA, float afB)
double Max(double adA, double adB)
int Max(int alA, int alB)
uint Max(uint aulA, uint aulB)
</syntaxhighlight>
Compares two numbers and returns whichever one is the larger value. This is the same as the global function MathMin(), except that it also takes an int, uint or double.
#''float afA, double adA, int alA, uint aulA'' - The first number to be compared.
#''float afB, double adB, int alB, uint aulB'' - The second number to be compared.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Max(10, lB);
// If lB is more than 10, lA will become equal to lB. Otherwise lA will become 10.
</syntaxhighlight>

====Clamp()====
<syntaxhighlight lang="cpp">
float Clamp(float afX, float afMin, float afMax)
double Clamp(double adX, double adMin, double adMax)
int Clamp(int alX, int alMin, int alMax)
uint Clamp(uint aulX, uint aulMin, uint aulMax)
</syntaxhighlight>
Limits a number to an allowed range. If the number is within the range then it is returned, otherwise the min or max is returned. This is the same as the global function MathClamp(), except that it also takes an int, uint or double.
#''float afX, double adX, int alX, uint aulX'' - The number to be compared.
#''float afMin, double adMin, int alMin, uint aulMin'' - The minimum of the allowed range.
#''float afMax, double adMax, int alMax, uint aulMax'' - The maximum of the allowed range.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Clamp(15, 10, 20);
float fB = Math.Clamp(25.0f, 10.0f, 20.0f);
// lA will be 15, but fB will be limited to 20.0f.
</syntaxhighlight>

====Wrap()====
<syntaxhighlight lang="cpp">
float Wrap(float afX, float afMin = 0.0f, float afMax = 1.0f);
double Wrap(double adX, double adMin = 0.0, double adMax = 1.0);
int Wrap(int alX, int alMin = 0, int alMax = 100);
</syntaxhighlight>
Returns a given number limited between a min and max using wrapping. Accepts float, double and int. Wrap() works similarly to Clamp(), except that if the given number is outside of the min and max, it will wrap back around using modulation.
 E.g. 2.75 wrapped between 1.0 and 2.0 will be 1.75.
 -1.25 wrapped between 0.0 and 1.0 will be 0.75.
#''float afX, double adX, or int alX'' - The number to be wrapped.
#''float afMin, double adMin, or int alMin'' - The inclusive lower boundary for wrapping. (Optional, float/double default = 0.0, int default = 0)
#''float afMax, double adMax, or int alMax'' - The exclusive upper boundary for wrapping. (Optional, float/double default = 1.0, int default = 100)
<syntaxhighlight lang="cpp">
// Example:
float fA = 2.75f;
float fB = -1.25f;
int lC = 125;
int lD = 100;
float fA_Wrapped = Math.Wrap(fA, 1.0, 2.0);
float fB_Wrapped = Math.Wrap(fB);
int lC_Wrapped = Math.Wrap(lC);
int lD_Wrapped = Math.Wrap(lD);
// The value of fA_Wrapped will be 1.75f.
// The value of fB_Wrapped will be 0.75f.
// The value of lC_Wrapped will be 25.
// The value of lD_Wrapped will be 0.
</syntaxhighlight>

===Rounding===
Math provides the following methods for converting floats to ints:

====Floor()====
<syntaxhighlight lang="cpp">
int Floor(float afX)
int Floor(double adX)
</syntaxhighlight>
Returns an int converted from a float or a double, by rounding 'down'.
#''float afX, double adX'' - The number to be rounded and returned as an int.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Floor(0.1f);
int lB = Math.Floor(0.5f);
int lC = Math.Floor(0.9f);
int lD = Math.Floor(-1.1f);
int lE = Math.Floor(-1.5f);
int lF = Math.Floor(-1.9f);
// lA, lB and lC all become 0.
// lD, lE and lF all become -2.
</syntaxhighlight>

====Ceiling()====
<syntaxhighlight lang="cpp">
int Ceiling(float afX)
int Ceiling(double adX)
</syntaxhighlight>
Returns an int converted from a float or a double, by rounding 'up'.
#''float afX, double adX'' - The number to be rounded and returned as an int.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Floor(0.1f);
int lB = Math.Floor(0.5f);
int lC = Math.Floor(0.9f);
int lD = Math.Floor(-1.1f);
int lE = Math.Floor(-1.5f);
int lF = Math.Floor(-1.9f);
// lA, lB and lC all become 1.
// lD, lE and lF all become -1.
</syntaxhighlight>

====Round()====
<syntaxhighlight lang="cpp">
int Round(float afX)
int Round(double adX)
</syntaxhighlight>
Returns an int converted from a float or a double, by rounding to the nearest whole number. When the float is on the midpoint (.5), Round() rounds 'away from zero'.
#''float afX, double adX'' - The number to be rounded and returned as an int.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Floor(0.1f);
int lB = Math.Floor(0.5f);
int lC = Math.Floor(0.9f);
int lD = Math.Floor(-1.1f);
int lE = Math.Floor(-1.5f);
int lF = Math.Floor(-1.9f);
// lA becomes 0. lB and lC both become 1.
// lD becomes -1. lE and lF both become -2.
</syntaxhighlight>

====RoundMidToEven()====
<syntaxhighlight lang="cpp">
int RoundMidToEven(float afX)
int RoundMidToEven(double adX)
</syntaxhighlight>
Returns an int converted from a float or a double, by rounding to the nearest whole number. When the float is on the midpoint (.5), RoundMidToEven() rounds 'towards the nearest even integer'.
#''float afX, double adX'' - The number to be rounded and returned as an int.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Floor(0.1f);
int lB = Math.Floor(0.5f);
int lC = Math.Floor(0.9f);
int lD = Math.Floor(-1.1f);
int lE = Math.Floor(-1.5f);
int lF = Math.Floor(-1.9f);
// lA and lB both become 0. lC becomes 1.
// lD becomes -1. lE and lF both become -2.
</syntaxhighlight>

====Truncate()====
<syntaxhighlight lang="cpp">
int Truncate(float afX)
int Truncate(double adX)
</syntaxhighlight>
Returns an int converted from a float or a double, by 'discarding the fractional part', rounding towards zero even if the fraction is part the midpoint.
 This is effectively the same as using "int(fX)".
#''float afX, double adX'' - The number to be rounded and returned as an int.
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.Floor(0.1f);
int lB = Math.Floor(0.5f);
int lC = Math.Floor(0.9f);
int lD = Math.Floor(-1.1f);
int lE = Math.Floor(-1.5f);
int lF = Math.Floor(-1.9f);
// lA, lB and lC all become 0.
// lD, lE and lF all become -1.
</syntaxhighlight>

===Interpolation===
Math provides the following methods for interpolating between values:

====Lerp()====
<syntaxhighlight lang="cpp">
float Lerp(float afA, float afB, float afAlpha, enumLimitType aLimitOption = limitFree)
double Lerp(double adA, double adB, double adAlpha, enumLimitType aLimitOption = limitFree)
cVector Lerp(cVector avA, cVector avB, float afAlpha, enumLimitType aLimitOption = limitFree)
int Lerp(int alA, int alB, float afAlpha, enumLimitType aLimitOption = limitFree)
</syntaxhighlight>
Linear interpolation: maps an alpha of 0.0-1.0, between values A and B.
 aLimitOption is optional and can be omitted, or it can be limitFree, limitClamped or limitWrapped.
 With limitFree (default) the alpha is not clamped.
 With limitClamped, the alpha value is limited to 0.0f-1.0f. E.g., -0.5f is the same as 0.0f, 3.0f is the same as 1.0f.
 With limitWrapped, the alpha values over 1 wrap around to zero. E.g., 1.5f is the same as 0.5f, -1.25f is the same as 0.75f.
 Accepts either float, double, or cVector. Can also work with two int values (and a float alpha), but note that the result will be truncated towards zero.
#''float afA, double adA, cVector avA, or int alA'' - The value corresponding to alpha 0.
#''float afB, double adB, cVector avB, or int alB'' - The value corresponding to alpha 1.
#''float afAlpha, double afAlpha'' - The alpha value of the interpolation.
#''enumLimitType aLimitOption'' - limitFree, limitClamped or limitWrapped '''(Optional, default = limitFree)'''
<syntaxhighlight lang="cpp">
// Example 1:
float fA = 5.0f;
float fB = 10.0f;
float fC = Math.Lerp(fA, fB, 2.0f/3.0f);
// fC is 8 1/3, which is 2/3 of the way from 5 to 10.

// Example 2:
FadeGlobalSoundSpeed(Math.Lerp(0.5f, 1.0f, GetPlayerSanity() / 100.0f) 1.0f);
// As the player loses sanity, sounds get slower.

// Example 3:
cVector vPlayerPos = Math.GetPlayerPosVec();
cVector vTargetPos = cVector(10.0f, 3.0f, 5.5f);
cVector vHalfwayToTarget = Math.Lerp(vPlayerPos, vTargetPos, 0.5f);
// vHalfwayToTarget is the midpoint between the player's location and the target location
</syntaxhighlight>

====WeightedAvg()====
<syntaxhighlight lang="cpp">
float WeightAvg(float afA, float afB, float afWeight = 0.5f)
double WeightAvg(double afA, double afB, double adWeight = 0.5)
cVector WeightAvg(cVector afA, cVector afB, float afWeight = 0.5f)
</syntaxhighlight>
Weighted average: returns a value interpolated between A and B, where weight defines how much "drag" there is. A common usage is to smooth out a number that is changing over time.
 The weight value can be thought of a how much A is "worth" compared to B (if B is "worth" 1.0). The lower the weight value, the closer to B the result will be. If weight is omitted it defaults to 0.5. Accepts pairs of float, double, or cVector.
#''float afA, double adA, or cVector avA'' - The current value of the interpolation.
#''float afB, double adB, or cVector avB'' - The target value of the interpolation.
#''float afWeight, double adWeight'' - The weight of the current value on the interpolation. '''(Optional, default = 0.5)'''
<syntaxhighlight lang="cpp">
// Example 1:
float fA = 100.0f;
float fB = 200.0f;
float fC = Math.WeightAvg(fA, fB, 2.0f);
// fC is 133 1/3, which is 1/3 of the way from 100 to 200.

// Example 2:
vFollowPos = Math.Lerp(Math.GetPlayerPosVec(), vFollowPos, 0.25f);
// An item placed at vFollowPos every frame will smoothly follow the player.
</syntaxhighlight>

====SnappingWeightedAvg()====
<syntaxhighlight lang="cpp">
float SnappingWeightedAvg(float afA, float afB, float afWeight, float afSnapSize = 0.001f)
double SnappingWeightedAvg(double afA, double afB, double adWeight, double adSnapSize = 0.001)
cVector SnappingWeightedAvg(cVector afA, cVector afB, float afWeight, float afSnapSize = 0.001f)
</syntaxhighlight>
Same as weighted average, but the new value will snap to A or B if it is in range. This can help to reduce slowly trailing values that don't noticebly change. If it is omitted, asSnapSize defaults to 0.001.
#''float afA, double adA, or cVector avA'' - The current value of the interpolation.
#''float afB, double adB, or cVector avB'' - The target value of the interpolation.
#''float afWeight, double adWeight'' - The weight of the current value on the interpolation.
#''float afSnapSize, double adSnapSize'' - The tolerance for snapping to A or B. (Optional, default = 0.001)
 

===Vector math===
Math provides the following methods for mathematic operations on vectors:

====Length()====
<syntaxhighlight lang="cpp">
float Length(cVector aVector, enumLengthType aSquaredOption = lengthFinal)
int Length(cPoint aVector, enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Returns the length a vector, i.e. it's displacement from 0,0,0.
 You can also use a cPoint to get the length as an int, but note that the result will be truncated. E.g. cVector(1.0f, 3.0f) has a length equal to the square root of 10, but cPoint(1, 3) has a length of 3 exactly.
 aSquaredOption can be omitted, or optionally can be either lengthFinal, lengthSquared. With lengthFinal (default), the value returned is the actual length. With lengthSquared, the value returned is length^2. This is much cheaper to calculate and good enough for a lot of situations. E.g. if you want to know which vector is longer but the actual length doesn't matter.
 Note: you can also use the Length() method of the vector classes. (e.g. myVec.Length() )
#''cVector aVector, cPoint aPoint'' - The vector to calculate the length of.
#''enumLengthType aSquaredOption'' - lengthFinal or lengthSquared '''(Optional, default = lengthFinal)'''
<syntaxhighlight lang="cpp">
// Example 1:
cVector vMyRectangle = cVector(10.0f, 15.0f);
float fMyHypotenuse = Math.Length(myRectangle);
// fMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.

// Example 2:
bool bIsVecALonger = Math.Length(vVecA, lengthSquared) > Math.Length(vVecB, lengthSquared);
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Distance()====
<syntaxhighlight lang="cpp">
float Distance(cVector avA, cVector avB, enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Returns the displacement between two vectors, e.g. the distance between two points in space.
 aSquaredOption can be omitted, or optionally can be either lengthFinal, lengthSquared. With lengthFinal (default), the value returned is the actual length. With lengthSquared, the value returned is length^2. This is much cheaper to calculate and good enough for a lot of situations. E.g. if you want to know which vector is longer but the actual length doesn't matter.
#''cVector avA'' - The start position of the distance.
#''cVector avB'' - The end position of the distance.
#''enumLengthType aSquaredOption'' - lengthFinal or lengthSquared '''(Optional, default = lengthFinal)'''
<syntaxhighlight lang="cpp">
// Example:
cVector vSomeplace = cVector(10.0f, 0.0f 15.0f);
cVector vSomeplaceElse = cVector(20.0f, 2.0f 25.0f);
float fDistance = Math.Distance(vSomeplace, vSomeplaceElse);
</syntaxhighlight>

====DistToPlayer()====
<syntaxhighlight lang="cpp">
float DistToPlayer(string asEntity, enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Returns the distance from an entity to the player.
 aSquaredOption can be omitted, or optionally can be either lengthFinal, lengthSquared. With lengthFinal (default), the value returned is the actual length. With lengthSquared, the value returned is length^2. This is much cheaper to calculate and good enough for a lot of situations. E.g. if you want to know which vector is longer but the actual length doesn't matter.
#''string asEntity'' - The entity whose location to compare to the player.
#''enumLengthType aSquaredOption'' - lengthFinal or lengthSquared '''(Optional, default = lengthFinal)'''
<syntaxhighlight lang="cpp">
// Example:
if (Math.DistToPlayer("Orb") < 12.0f) SetPlayerSanity(0.0f);
// When the player is less than 12m away from the orb, they lose all sanity points.
</syntaxhighlight>

====DistToEntity()====
<syntaxhighlight lang="cpp">
float DistToEntity(string asEntityA, string asEntityB, enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Returns the distance between two named entities.
 aSquaredOption can be omitted, or optionally can be either lengthFinal, lengthSquared. With lengthFinal (default), the value returned is the actual length. With lengthSquared, the value returned is length^2. This is much cheaper to calculate and good enough for a lot of situations. E.g. if you want to know which vector is longer but the actual length doesn't matter.
#''string asEntityA'' - The first entity whose location will be compared.
#''string asEntityB'' - The second entity whose location will be compared.
#''enumLengthType aSquaredOption'' - lengthFinal or lengthSquared '''(Optional, default = lengthFinal)'''
<syntaxhighlight lang="cpp">
// Example:
if (Math.DistToEntity("OrbPieceA", "OrbPieceB") < 1.0f)
{
cVector snapPos = Math.Lerp(Math.GetEntityPosVec("OrbPieceA"), Math.GetEntityPosVec("OrbPieceB"), 0.5f);
Math.SetEntityPosVec("OrbPieceA", snapPos);
Math.SetEntityPosVec("OrbPieceB", snapPos);
}
// When the two orb pieces are less than a metre apart, they snap together.
</syntaxhighlight>

====GetRelative()====
<syntaxhighlight lang="cpp">
cVector GetRelative(cVector avPosition, cVector avOriginA, cVector avOriginB)
cPoint GetRelative(cPoint avPosition, cPoint avOriginA, cPoint avOriginB)
</syntaxhighlight>
Given a world position vector in relation to origin A, this will return a world position with the same displacement from origin B. See also: TeleportPlayerRelative() and TeleportEntityRelative().
#''cVector avPosition or cPoint avPosition'' - A vector defining a start position.
#''cVector avOriginA or cPoint avOriginA'' - A position in relation to the start position.
#''cVector avOriginB or cPoint avOriginB'' - A position in relation to the output position.
<syntaxhighlight lang="cpp">
// Example:
cVector vMirrorWorldPlayerPos = Math.GetRelative(Math.GetPlayerPosVec(), vNormalWorldCentre, vMirrorWorldCentre) * cVector(1.0f, 1.0f, -1.0f);
// This convoluted example is something you might be interested in if you were trying to make a fake mirror, perhaps.
</syntaxhighlight>

====TeleportPlayerRelative()====
<syntaxhighlight lang="cpp">
void TeleportPlayerRelative(string asAreaA, string asAreaB)
</syntaxhighlight>
Moves the player to a location relative to a named area B, whilst maintaining their position relative to area A.
#''string asAreaA'' - Name of an area (or other entity) in relation to the player's current position.
#''string asAreaB'' - Name of an area (or other entity) in relation to the player's new position.
<syntaxhighlight lang="cpp">
// Example:
Math.TeleportPlayerRelative("Room1Area", "Room2Area");
// Assuming Room1Area and Room2Area are the same size/shape, if the player is inside Room1Area, they will teleport to the same position inside Room2Area.
</syntaxhighlight>

====TeleportEntityRelative()====
<syntaxhighlight lang="cpp">
void TeleportPlayerRelative(string asEntity, string asAreaA, string asAreaB)
</syntaxhighlight>
Moves the named entity to a location relative to a named area B, whilst maintaining its position relative to area A.
#''string asEntity'' - Name of the entity to teleport.
#''string asAreaA'' - Name of an area (or other entity) in relation to the player's current position.
#''string asAreaB'' - Name of an area (or other entity) in relation to the player's new position.
<syntaxhighlight lang="cpp">
// Example:
Math.TeleportEntityRelative("FatSackOfThalers", "Room1Area", "Room2Area");
// Assuming Room1Area and Room2Area are the same size/shape, if FatSackOfThalers is inside Room1Area, it will teleport to the same position inside Room2Area.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cVector Normal(cVector avX)
cPoint Normal(cPoint avX)
</syntaxhighlight>
Returns a normalized copy of a vector, without changing the original. (A normalized vector has the same direction, but with a length forced to 1.) Accepts a cVector or cPoint. Uses SafeDivide() to avoid ...impossible geometry!
#''cVector avX or cPoint avX'' - The vector to calculate the normal off.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = Math.Normal(vDirection) * fSpeed;
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of exactly fSpeed.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normal(cVector avX)
void Normal(cPoint avX)
</syntaxhighlight>
Normalizes the specified vector in place, replacing the original. (A normalized vector has the same direction, but with a length forced to 1.) Accepts a cVector or cPoint. Uses SafeDivide() to avoid ...impossible geometry!
#''cVector avX or cPoint avX'' - The vector to be replaced with its normal.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
Math.Normalize(vVelocity); // Length of vVelocity has now become 1.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Math.Normal().
</syntaxhighlight>

====DotProduct()====
<syntaxhighlight lang="cpp">
float DotProduct(cVector avA, cVector avB)
</syntaxhighlight>
Returns the dot product (a.k.a. inner product) of two vectors. The * operator between two vectors also returns the dot product.
#''cVector avA'' - The first vector to use in the dot product calculation.
#''cVector avB'' - The second vector to use in the dot product calculation.
<syntaxhighlight lang="cpp">
// Example:
float fDotMath = Math.DotProduct(vMyVecA, vMyVecB);
float fDotStar = vMyVecA * vMyVecB;
// fDotMath is equal to fDotStar
</syntaxhighlight>

====CrossProduct3d()====
<syntaxhighlight lang="cpp">
cVector CrossProduct3d(cVector avA, cVector avB)
</syntaxhighlight>
Returns the cross product of two 3d vectors.
#''cVector avA'' - The first vector to use in the cross product calculation.
#''cVector avB'' - The second vector to use in the cross product calculation.
<syntaxhighlight lang="cpp">
// Example:
cVector vMyVecC = Math.CrossProduct3d(vMyVecA, vMyVecB);
</syntaxhighlight>

====ParallelVectors()====
<syntaxhighlight lang="cpp">
float ParallelVectors(cVector avA, cVector avB, bool abAbsolute = true)
</syntaxhighlight>
Given two vectors or two 3d vectors, ParallelVectors will return a float indicating how parallel they are. If the returned float is 0 (or nearly 0), then the vectors are perpendicular (or nearly perpendicular). If the returned float is 1 (or nearly 1), then the vectors are parallel (or nearly parallel).
 abAbsolute is optional. If omitted, it defaults to true. If true, the return value will always be positive and indicates whether the vectors are parallel. If abAbsolute is false, the return value may be negative. A value of -1 would indicate that the vectors are
parallel, but pointing in the opposite direction.
#''cVector avA'' - First vector to compare.
#''cVector avB'' - Second vector to compare.
#''bool abAbsolute'' - If false, a negative return value indicates parallel-but-opposite. '''(Optional, default = true)'''
<syntaxhighlight lang="cpp">
// Example 1:
float fRighthand = Math.ParallelVectors(cVector(0.0f, 0.0f, 1.0f), cVector(-1.0f, 0.0f, 0.0f));
float fBackDiagonal = Math.ParallelVectors(cVector(0.0f, 0.0f, 1.0f), cVector(0.5f, 0.0f, -1.0f), false);
// The value of fRighthand will be 0. The value of fBackDiagonal will be -0.894427.

// Example 2:
bfollowingPath = ParallelVectors(vPlayerPosCurr - vPlayerPosPrev, vPathDir, false) > 0.75f;
// Assuming vPlayerPosCurr is the current position of the player, and vPlayerPosPrev is the previous position of the player, and vPathDir is some direction we want the player to move along, then the bool bFollowingPath becomes true if the player is moving roughly in the direction of the path.
</syntaxhighlight>

====IsParallel()====
<syntaxhighlight lang="cpp">
bool IsParallel(cVector avA, cVector avB)
</syntaxhighlight>
Given two vectors, IsParallel() returns true if they are parallel, allowing for a small margin of error.
#''cVector avA'' - First vector to compare.
#''cVector avB'' - Second vector to compare.
<syntaxhighlight lang="cpp">
// Example 1:
bool bPar = Math.IsParallel(cVector(1.0f, 0.0f, 0.0f), cVector(0.0f, 0.0f, 0.1f));
// The value of bPar will be false.

// Example 2:
if (Math.IsParallel(Math.GetEntityPosVec("puzzlePieceA") - Math.GetEntityPosVec("puzzlePieceB"), Math.GetEntityPosVec("puzzlePieceB") - Math.GetEntityPosVec("puzzlePieceC"))) PuzzleSolved();
// The condition succeeds when the three puzzle pieces have been placed in a line.
</syntaxhighlight>

====IsPerpendicular()====
<syntaxhighlight lang="cpp">
bool IsPerpendicular(cVector avA, cVector avB)
</syntaxhighlight>
Given two vectors, IsPerpendicular() returns true if they are are perpendicular, allowing for a small margin of error.
#''cVector avA'' - First vector to compare.
#''cVector avB'' - Second vector to compare.
<syntaxhighlight lang="cpp">
// Example 1:
bool bPar = Math.IsPerpendicular(cVector(1.0f, 0.0f, 0.0f), cVector(0.0f, 0.0f, 0.1f));
// The value of bPar will be true.

// Example 2:
if (Math.IsPerpendicular(Math.GetEntityPosVec("puzzlePieceA") - Math.GetEntityPosVec("puzzlePieceB"), Math.GetEntityPosVec("puzzlePieceB") - Math.GetEntityPosVec("puzzlePieceC"))) PuzzleSolved();
// The condition succeeds when the three puzzle pieces have been placed in a right-angled triangle.
</syntaxhighlight>

====RotateVector2d()====
<syntaxhighlight lang="cpp">
cVector RotateVector2d(cVector avA, float afB, enumAngleUnits aUnits = angleDegrees)
</syntaxhighlight>
Given a 2d vector and an angle, this rotates the vector by the specified amount and returns the new rotated 2d vector. A positive angle is a clockwise rotation, negative is anticlockwise.
 aUnits can be omitted, or optionally it can be angleDegrees or angleRadians. With angleDegrees (default), the given angle afB is taken as degrees. With angleRadians, the given angle afB is taken as radians.
#''cVector avA'' - The vector to be rotated.
#''float afB'' - The angle to rotate by.
#''enumAngleUnits aUnits'' - angleDegrees or angleRadians. '''(Optional, default = angleDegrees)'''
<syntaxhighlight lang="cpp">
// Example 1:
cVector vVecA = cVector(1.0f, 0.0f);
cVector vVecB = cVector(0.0f, 1.0f);
cVector vVecC = Math.RotateVector2d(vVecA, 90.0f);
// vVecB and vVecC are equal.

// Example 2:
cVector vDirOnPlane = Math.RotateVector2d(cVector(-1.0f, 0.0f), Math.Pi * Math.RandomFloat(-0.125f, 0.125f));
// vDirOnPlane becomes a random 2d vector pointing roughly rightwards.
</syntaxhighlight>

====AngleToVector2d()====
<syntaxhighlight lang="cpp">
cVector AngleToVector2d(float afA, enumAngleUnits aUnits = angleDegrees)
</syntaxhighlight>
Converts an angle on a 2d plane to a 2d forward vector, using either degrees or radians.
 Note that 0d rotation is pointing upward, and in the returned vector the origin is in the top-left: 0 degrees = 12 o'clock = (0, -1); 90 degrees = 3 o'clock = (1, 0)
 aUnits can be omitted, or optionally it can be angleDegrees or angleRadians. With angleDegrees (default), the given angle afB is taken as degrees. With angleRadians, the given angle afB is taken as radians.
#''float afR, float afD'' - The angle to convert to a 2d vector.
#''enumAngleUnits aUnits'' - angleDegrees or angleRadians. '''(Optional, default = angleDegrees)'''
<syntaxhighlight lang="cpp">
// Example:
cVector vVecA = Math.AngleToVector2d(90.0f);
cVector vVecB = Math.AngleToVector2d(180.0f);
cVector vVecC = Math.RotateVector2d(vVecA, 90.0f);
// vVecB and vVecC are equal.
</syntaxhighlight>

====Vector2dToAngle()====
<syntaxhighlight lang="cpp">
float Vector2dToAngle(cVector avA, enumAngleUnits aUnits = angleDegrees)
</syntaxhighlight>
Converts a 2d forward vector to an angle on the 2d plane, using either degrees or radians.
 Note that 0d rotation is pointing upward, and in the returned vector the origin is in the top-left: 0 degrees = 12 o'clock = (0, -1); 90 degrees = 3 o'clock = (1, 0)
 aUnits can be omitted, or optionally it can be angleDegrees or angleRadians. With angleDegrees (default), the given angle afB is taken as degrees. With angleRadians, the given angle afB is taken as radians.
#''cVector avA'' - A 2d vector to convert to an angle.
#''enumAngleUnits aUnits'' - angleDegrees or angleRadians. '''(Optional, default = angleDegrees)'''
<syntaxhighlight lang="cpp">
// Example:
float fRad = Math.Vector2dToAngle(cVector(3.0f, 1.5f));
// fRad is equal to 3/8*Pi.
</syntaxhighlight>

====RotateVector3d()====
<syntaxhighlight lang="cpp">
cVector RotateVector3d(cVector avA, cRotator arB)
</syntaxhighlight>
Given a 3d vector and a pitch-yaw-roll rotator, this rotates the vector by the specified amount, and returns the new rotated vector.
 Note that HPL2 uses a "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1.
#''cVector avA'' - The vector to be rotated.
#''cRotator arB'' - The rotator containing the pitch, yaw and roll angles.
<syntaxhighlight lang="cpp">
// Example 1:
cVector vForward = cVector(0.0f, 0.0f 1.0f);
cRotator vPitchDown = cRotator(5.0f, 0.0f, 5.0f, angleDegrees);
vForward = Math.RotateVector3d(vForward, vPitchDown);
// vForward has been tilted slightly downwards and leaned slightly rightwards.

// Example 2:
cVector vForward = cVector(0.0f, 0.0f 1.0f);
cRotator vBarrelRoll = cRotator(0.0f, 0.0f, 180.0f, angleDegrees);
vForward = Math.RotateVector3d(vForward, vBarrelRoll);
// vForward hasn't changed. Roll on it's own does nothing to a vector, since a vector has no sense of "orientation", only "forward".
</syntaxhighlight>

====RotatorToVector3d()====
<syntaxhighlight lang="cpp">
cVector RotatorToVector3d(cRotator arRot, enumOrthoDir aDirectionOption = dirForward)
</syntaxhighlight>
Converts a rotator with pitch, yaw and roll angles into a 3d directional vector. This is basically the same as RotateVector3d() but perhaps more convenient.
 aDirectionOption is optional and specifies an orthogonal world vector to use. It can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown. If omitted it defaults to dirForward.
 Note that HPL2 uses a "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. If an entity was facing 0,0,1 before rotation, then RotatorToVector3d() with dirForward would return it's facing direction after rotation.
#''cRotator arRot'' - Rotator containing pitch, yaw, roll values to convert to a vector.
#''enumOrthoDir aDirectionOption'' - Which orthoginal world vector to rotate. '''(Optional, default = dirForward)'''
<syntaxhighlight lang="cpp">
// Example:
cRotator vPitchUp = cRotator(-0.25f * Math.Pi, 0.0f, 0.0f, angleRadians);
cVector vForwardUp = Math.RotatorToVector3d(vPitchDown);
cVector vRightUp = Math.RotatorToVector3d(vPitchDown, dirRight);
// vForwardUp points forward, tilted up by 45 degrees. vRightUp points rightward, tilted up by 45 degrees.
</syntaxhighlight>

====Vector3dToRotator()====
<syntaxhighlight lang="cpp">
cRotator Vector3dToRotator(cVector avForward)
cRotator Vector3dToRotator(cVector avForward, cVector avUp)
</syntaxhighlight>
Converts a 3d directional vector to pitch, yaw and roll, and returns the result as a rotator.
 If only one vector is given then it represents the forward direction, and the returned rotator will have a yaw and pitch rotated to that forward direction. The roll will be zero.
 An optional second vector can be provided in order to calculate roll. If the second vector is given then the first represents the forward direction and the second represents the upward direction. The returned rotator will include a roll angle calculated using the upward direction.
#''cVector avForward'' - The forward directional vector to be converted to a rotator.
#''cVector avUp'' - Optional upward directional vector used to calculate roll. '''(Optional, default = no roll)'''
<syntaxhighlight lang="cpp">
// Example:
cRotator vMyRot = Math.Vector3dToRotator(cVector(-1.0f, 0.0f, -1.0f));
if (vMyRot.YawDeg > 90.0f) DoStuff();
// The condition succeeds because vMyRot becomes a yaw rotation of 135 degrees clockwise.
</syntaxhighlight>

===Vector replacements===
The following math methods are intended to replace some of the normal global functions that use separate X, Y and Z floats:

====GetPlayerPosVec()====
<syntaxhighlight lang="cpp">
cVector GetPlayerPosVec()
</syntaxhighlight>
Returns the player's location as a 3d cVector, instead of [[HPL2/Engine_Scripts#Player|GetPlayerPosX/Y/Z()]], which only return a single float.)
<syntaxhighlight lang="cpp">
// Example:
cVector vPlayerCurrPos = Math.GetPlayerPosVec();
// Stores the player's current location in a cVector.
</syntaxhighlight>

====SetPlayerPosVec()====
<syntaxhighlight lang="cpp">
void SetPlayerPosVec(cVector avPos)
</syntaxhighlight>
Moves the player to a location given as a 3d cVector, instead of [[HPL2/Engine_Scripts#Player|SetPlayerPos()]], which takes separate 3 floats.
#''cVector avPos'' - The new location for the player.
<syntaxhighlight lang="cpp">
// Example:
cVector vOrigin;
Math.SetPlayerPosVec(vOrigin);
// Teleports the player to the world origin.
</syntaxhighlight>

====MovePlayerHeadPosVec()====
<syntaxhighlight lang="cpp">
void MovePlayerHeadPosVec(cVector avPos, float afSpeed, float afSlowDownDist)
</syntaxhighlight>
Changes the position of the camera on the player's body, using a 3d cVector, instead of [[HPL2/Engine_Scripts#Player|MovePlayerHeadPos()]], which takes separate 3 floats.
#''cVector avPos'' - The new location for the player's head.
#''float afSpeed - The speed at which the change happens.
#''float afSlowDownDist - The distance at which to start slowing down (prevents the head from abruptly stopping).
<syntaxhighlight lang="cpp">
// Example:
Math.MovePlayerHeadPosVec(my3dVector, 1.5f, 0.1f);
// Moves the player camera to whatever offset is assigned to my3dVector.
</syntaxhighlight>

====GetEntityPosVec()====
<syntaxhighlight lang="cpp">
cVector GetEntityPosVec(string asEntity)
</syntaxhighlight>
Returns the named entity's location as a 3d cVector, instead of [[HPL2/Engine_Scripts#Entities|GetEntityPosX/Y/Z()]], which only return a single float.
#''string asEntity'' - The entity to be moved.
<syntaxhighlight lang="cpp">
// Example:
cVector vHammerCurrPos = Math.GetEntityPosVec("hammer");
// Stores the hammer's current location in a cVector.
</syntaxhighlight>

====SetEntityPosVec()====
<syntaxhighlight lang="cpp">
void SetEntityPosVec(string asEntity, cVector avPos)
</syntaxhighlight>
Moves the named entity to a location given as a 3d cVector, instead of [[HPL2/Engine_Scripts#Entities|SetEntityPos()]], which takes separate 3 floats.
#''string asEntity'' - The entity to be moved.
#''cVector avPos'' - The new location for the entity.
<syntaxhighlight lang="cpp">
// Example:
Math.SetEntityPosVec("anvil", Math.GetPlayerPosVec() + cVector(0.0f, 3.0f, 0.0f));
// Teleports the entity "anvil" to 3m above the player.
</syntaxhighlight>

====AddPropForceVec etc====
<syntaxhighlight lang="cpp">
void AddPropForceVec(string asName, cVector avForce, string asCoordSystem = "world")
void AddPropImpulseVec(string asName, cVector avImpulse, string asCoordSystem = "world")
void AddBodyForceVec(string asName, cVector avForce, string asCoordSystem = "world")
void AddBodyImpulseVec(string asName, cVector avImpulse, string asCoordSystem = "world")
</syntaxhighlight>
These functions are provided as a way to use the global functions [[HPL2/Engine_Scripts#Props|AddPropForce() etc.]], with a vector specifying the force or impulse, rather than floats. Could be useful if you want to use it with e.g. RandomVector3d(). See the documentation for the original functions for more information. The asCoordSystem string argument is optional in these versions.
#''string asName'' - The name of the entity or body to push.
#''cVector avForce, cVector avImpulse'' - A 3d vector to use for the force or impulse.
#''string asCoordSystem'' - Frame of reference for the force. '''(Optional, default = "world")'''
 

====RotatePropToSpeedVec()====
<syntaxhighlight lang="cpp">
void RotatePropToSpeedVec(string asName, float afAcc, float afGoalSpeed, cVector avAxes, bool abResetSpeed = false, string& asOffsetArea = "")
</syntaxhighlight>
This function is provided as a way to use the global function [[HPL2/Engine_Scripts#Props|RotatePropToSpeed()]] with a vector as the axis multiplier, instead of floats. Could be useful if you want to use it with e.g. RandomVector3d(). See the documentation for the original function for more information. The asOffsetArea string and abResetSpeed bool arguments are optional in this version.
#''string asName'' - Name of the prop to rotate.
#''float afAcc'' - Acceleration used to reach desired speed.
#''float afGoalSpeed'' - The desired speed.
#''cVector avAxes'' - The 3d vector to use as the axis multiplier.
#''bool abResetSpeed'' - Whether to reset the speed after the goal is reached. '''(Optional, default = false)'''
#''string asOffsetArea'' - The area to rotate around. If empty, the center of the body is used. '''(Optional, default = "")'''
 

===Randomness===
Math provides the following methods for returning random values:

====RandomBool()====
<syntaxhighlight lang="cpp">
bool RandomBool()
</syntaxhighlight>
Returns a bool with a 50% chance of being true.
<syntaxhighlight lang="cpp">
// Example 1:
bool bSomeBool = Math.RandomBool();
// bSomeBool might be true or false.

// Example 2:
if (Math.RandomBool) SimonIsDuplicate();
else SimonIsOriginal();
// No explanation.
</syntaxhighlight>

====RandomFloat()====
<syntaxhighlight lang="cpp">
float RandomFloat()
float RandomFloat(float afMin, float afMax)
</syntaxhighlight>
Returns a random float. The min and max numbers are optional. If a min and max are provided, this is the same as the normal global function RandFloat(). (Note the name difference: Math.RandomFloat() vs RandFloat().)
 If the min and max numbers are omitted, then RandomFloat() will return a random float between zero and one.
#''float afMin'' - The minimum range of the random number. '''(Optional, together with afMax)'''
#''float afMax'' - The maximum range of the random number. '''(Optional, together with afMin)'''
<syntaxhighlight lang="cpp">
// Example:
float fA = Math.RandomFloat();
float fB = Math.RandomFloat(-0.25f, 0.25f);
float fC = Math.RandomFloat() * 0.5f - 0.25f;
// fA becomes a random float in the range 0.0...1.0.
// fB and fC both have the same range: -0.25...0.25.
</syntaxhighlight>

====RandomInt()====
<syntaxhighlight lang="cpp">
int RandomInt()
int RandomInt(int alMin, int alMax)
</syntaxhighlight>
Returns a random int. The min and max numbers are optional. If a min and max are provided, this is the same as the normal global function RandInt(). (Note the name difference: Math.RandomInt() vs RandInt().)
 If the min and max numbers are omitted, then RandomInt() will return a random integer in the maximum range of a signed 32bit integer: -2^31...2^31-1 (-2147483648...2147483647).
#''int alMin'' - The inclusive minimum range of the random number. '''(Optional, together with alMax)'''
#''int alMax'' - The exclusive maximum range of the random number. '''(Optional, together with alMin)'''
<syntaxhighlight lang="cpp">
// Example:
int lA = Math.RandomInt();
int lB = Math.RandomInt(0, 6);
int lC = Math.RandomInt(1, 7);
// lA becomes any possible signed 32bit int.
// lB and lC both have 6 possible outcomes: lB could be 0...5, and lC could be 1...6.
</syntaxhighlight>

====RandomUint()====
<syntaxhighlight lang="cpp">
uint RandomUint()
</syntaxhighlight>
Returns a random uint in the maximum range possible. The upper limit of an unsigned 32bit int should be 2^32, but we only have the means of generating 'signed' ints in script, so RandomUint() will actually return a random integer from zero to 2^31-1, inclusive (0...2147483647).
 

====RandomInt16()====
<syntaxhighlight lang="cpp">
int16 RandomInt16()
</syntaxhighlight>
Returns a random int16 in the maximum range of a signed 16bit integer, inclusive: -2^15...2^15-1 (-32768...32767).
 

====RandomUint16()====
<syntaxhighlight lang="cpp">
uint16 RandomInt16()
</syntaxhighlight>
Returns a random uint16 in the maximum range of an usigned 16bit integer, inclusive: 0...2^16-1 (0...65535).
 

====RandomInt8()====
<syntaxhighlight lang="cpp">
int8 RandomInt16()
</syntaxhighlight>
Returns a random int8 in the maximum range of a signed 8bit integer, inclusive: -2^7...2^7-1 (-128...127).
 

====RandomUint8()====
<syntaxhighlight lang="cpp">
uint8 RandomInt16()
</syntaxhighlight>
Returns a random uint8 in the maximum range of an usigned 8bit integer, inclusive: 0...2^16-1 (0...255).
 

====RandomVector2d()====
<syntaxhighlight lang="cpp">
cVector RandomVector2d(float afMin = 0.0f, float afMax = 1.0f, enumVecType aVecOption = vecFree)
</syntaxhighlight>
Returns a random 2d vector. aVecOption can be omitted, or optionally can be either vecFree, vecOrtho or vecNormal. With vecFree (default), a vector is returned where each dimension is an unrelated random number from afMin to afMax. With vecOrtho, a vector is returned with length afMax, pointing in one positive or negative orthogonal direction. With vecNormal, a normal vector is returned, scaled by afMax (with a length of afMax and a random direction).
 afMin and afMax are also optional. If omitted, they default to 0.0f and 1.0f.
#''float afMin'' - Used with afMax to specify the minimum extent of the random vector. (Optional with afMax, default = 0.0f)
#''float afMax'' - Used with afMin 'or on it's own' to specify the maximum extent of the random vector. (Optional, default = 1.0f)
#''enumVecType aVecOption'' - vecFree, vecOrtho or vecNormal. Specifies the type of random vector returned. (Optional, default = vecFree)
<syntaxhighlight lang="cpp">
// Example:
cVector vA = Math.RandomVector2d(5.0f, 10.0f);
cVector vB = Math.RandomVector2d(vecOrtho);
cVector vC = Math.RandomVector2d(3.5f, vecNormal);
// vA becomes a 2d vector where x and y are both random floats in the range of 5.0...10.00.
// vB becomes a 2d vector with a length of 1.0, pointing directly up, down, left or right.
// vC becomes a 2d vector pointing in any 2d direction, with a length of 3.5.
</syntaxhighlight>

====RandomVector3d()====
<syntaxhighlight lang="cpp">
cVector RandomVector3d(float afMin = 0.0f, float afMax = 1.0f, enumVecType aVecOption = vecFree)
</syntaxhighlight>
Returns a random 3d vector. aVecOption can be omitted, or optionally can be either vecFree, vecOrtho or vecNormal. With vecFree (default), a vector is returned where each dimension is an unrelated random number from afMin to afMax. With vecOrtho, a vector is returned with length afMax, pointing in one positive or negative orthogonal direction. With vecNormal, a normal vector is returned, scaled by afMax (with a length of afMax and a random direction).
 afMin and afMax are also optional. If omitted, they default to 0.0f and 1.0f.
#''float afMin'' - Used with afMax to specify the minimum extent of the random vector. (Optional with afMax, default = 0.0f)
#''float afMax'' - Used with afMin 'or on it's own' to specify the maximum extent of the random vector. (Optional, default = 1.0f)
#''enumVecType aVecOption'' - vecFree, vecOrtho or vecNormal. Specifies the type of random vector returned. (Optional, default = vecFree)
<syntaxhighlight lang="cpp">
// Example:
cVector vA = Math.RandomVector3d(5.0f, 10.0f);
cVector vB = Math.RandomVector3d(vecOrtho);
cVector vC = Math.RandomVector3d(3.5f, vecNormal);
// vA becomes a 3d vector where x, y and z are all random floats in the range of 5.0...10.00.
// vB becomes a 3d vector with a length of 1.0, pointing directly forward, backward, up, down, left or right.
// vC becomes a 3d vector pointing in any 3d direction, with a length of 3.5.
</syntaxhighlight>

====RandomVectorInBounds()====
<syntaxhighlight lang="cpp">
cVector RandomVectorInBounds(cVector avMin, cVector avMax, enumVecType aVecOption = vecFree)
</syntaxhighlight>
Given a pair of cVector to define the extents of a rectangle or box, this will return a random position within those extents.
 aVecOption can be omitted, or optionally can be either vecFree, vecOrtho or vecNormal. With vecFree (default), a vector is returned where each dimension is an unrelated random number from afMin to afMax. With vecOrtho, a vector is returned with length afMax, pointing in one positive or negative orthogonal direction. With vecNormal, a normal vector is returned, scaled by afMax (with a length of afMax and a random direction).
 To put it another way: vecFree returns a position inside a quad/cuboid, vecOrtho returns a single extent of the quad/cuboid, and vecNormal returns a point on a circle/sphere that fits the quad/cuboid.
#''cVector avMin'' - A cVector defining the minimum extent of the range for the random position.
#''cVector avMax'' - A cVector defining the maximum extent of the range for the random position.
#''enumVecType aVecOption'' - vecFree, vecOrtho or vecNormal. Specifies the type of random vector returned. (Optional, default = vecFree)
<syntaxhighlight lang="cpp">
// Example 1:
cVector vA = Math.RandomVectorInBounds(cVector(-5.0f, -5.0f, -5.0f), cVector(5.0f, 5.0f, 5.0f));
cVector vB = Math.RandomVectorInBounds(cVector(-5.0f, 0.0f, 2.0f), cVector(5.0f, 10.0f, 2.0f));
// vA becomes random position in a cube centred on 0,0,0, with a size of 10m.
// vB becomes random position on an x/y plane 2m forward, -5,0,2...5,10,2.

// Example 2:
cVector vMyRoom_FloorCornerA = cVector(20.0f. 0.0f, 30.0f);
cVector vMyRoom_FloorCornerB = cVector(10.0f. 0.0f, 15.0f);
float fMyRoom_CeilingHeight = 4.0f;
cVector vMyRoom_RandomPosOnFloor = Math.RandomVectorInBounds(vMyRoom_FloorCornerA, vMyRoom_FloorCornerB);
cVector vMyRoom_RandomPosOnCeiling = Math.RandomVectorInBounds(vMyRoom_FloorCornerA, vMyRoom_FloorCornerB) + cVector(0.0f, fMyRoom_CeilingHeight, 0.0f);
cVector vMyRoom_RandomPosInRoom = Math.RandomVectorInBounds(vMyRoom_FloorCornerA, vMyRoom_FloorCornerB + cVector(0.0f, fMyRoom_CeilingHeight, 0.0f));
cVector vMyRoom_RandomSurface = Math.RandomVectorInBounds(vMyRoom_FloorCornerA, vMyRoom_FloorCornerB + cVector(0.0f, fMyRoom_CeilingHeight, 0.0f), vecOrtho);
cVector vMyRoom_RandomSphere = Math.RandomVectorInBounds(vMyRoom_FloorCornerA, vMyRoom_FloorCornerB + cVector(0.0f, fMyRoom_CeilingHeight, 0.0f), vecNormal);
// Assuming that we have a room that is cuboid in shape:
// vMyRoom_RandomPosOnFloor and vMyRoom_RandomPosOnCeiling become random points on the floor and ceiling.
// vMyRoom_RandomPosInRoom becomes a random position anywhere in the room.
// vMyRoom_RandomSurface becomes a point in the centre of either the ceiling, floor or any of the four walls.
// vMyRoom_RandomSphere becomes a random position inside the a sphere that reaches from the centre of the room to the nearest surface.
</syntaxhighlight>

====RandomRotator()====
<syntaxhighlight lang="cpp">
cRotator RandomRotator(float afMinPitch = -Pi, float afMaxPitch = Pi, float afMinYaw = -Pi, float afMaxYaw = Pi, float afMinRoll = -Pi, float afMaxRoll = Pi, enumAngleUnits aUnits = angleRadians)
</syntaxhighlight>
Returns a random rotator. The arguments are optional all together. If all are omitted, the rotator will have an entirely random orientation. If all are included, then the random orientation will be within the specified range.
 aUnits is optional and defaults to angleRadians if omitted. If angleRadians (default) the min and max values are assumed to be in radians. If angleDegrees, they are assumed to be in degrees.
#''float afMinPitch'' - Lower limit for pitch. (Optional with all together, default = -Pi)
#''float afMaxPitch'' - Upper limit for pitch. (Optional with all together, default = Pi)
#''float afMinYaw'' - Lower limit for yaw. (Optional with all together, default = -Pi)
#''float afMaxYaw'' - Upper limit for yaw. (Optional with all together, default = Pi)
#''float afMinRoll'' - Lower limit for roll. (Optional with all together, default = -Pi)
#''float afMaxRoll'' - Upper limit for roll. (Optional with all together, default = Pi)
#''enumAngleUnits aUnits'' - angleRadians, or angleDegrees. (Optional, default = angleRadians)
<syntaxhighlight lang="cpp">
// Example:
cRotator vRotA = Math.RandomRotator();
cRotator vRotB = Math.RandomRotator(-5.0f, 5.0f, -180.0f, 180.0f, 0.0f, 0.0f, angleDegrees);
cRotator vRotC = Math.RandomRotator(-Math.Pi/36.0f, Math.Pi/36.0f, -Math.Pi, Math.Pi, 0.0f, 0.0f);
// vRotA becomes a random rotator with any possible orientation.
// vRotB and vRotC both have the same possible range, one provided in degrees, the other in radians. In both cases the rotation is tilted slightly up or down and pitched to any direction, with no roll.
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2024-02-11T01:52:41Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.

There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====Capacity====
<syntaxhighlight lang="cpp">
uint Capacity
</syntaxhighlight>
The read-only integer property Capacity returns the maximum count of items in the list. This will be the default limit, unless one was specified on construction.
<syntaxhighlight lang="cpp">
// Example:
cListInt someList;
someList.Add(1);
uint spaceRemaining = someList.Capacity - someList.Count;
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

====DefaultValue====
<syntaxhighlight lang="cpp">
int DefaultValue
float DefaultValue
double DefaultValue
bool DefaultValue
string DefaultValue
cVector DefaultValue
cPoint DefaultValue
cRotator DefaultValue
</syntaxhighlight>
The read-only property DefaultValue returns the value that this list type uses as a default. The default value is defined by each list class and used instead of a null item. (e.g.: -1, 0.0f, false, "")
<syntaxhighlight lang="cpp">
// Example:
someItem = myList.Pop();
if (someItem == myList.DefaultValue) Debug.Message(1, "Nothing left to pop!");
// The condition succeeds if item returned from the list was the default item, probably because the list was empty.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Equality===

The logical equality operator (double equals sign "==") can be used to compare two lists of the same type, just like with other values. It will return true if the lists contain the same number of items and the coresponding data items in the lists have equal values, or if the two lists both point to the same data.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB;
listA.Add("four");
listA.Add("five");
listA.Add("size");

cListString listC = listB;

bool test1 = listA == listB;
bool test2 = listB == listC;
// test1 will be false because listA and listB contain values that are not equal.
// test2 will be true because listB and listC both point to the same items.
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem, bool abExtend = true)
bool Set(uint aulIndex, float afItem, bool abExtend = true)
bool Set(uint aulIndex, double adItem, bool abExtend = true)
bool Set(uint aulIndex, bool abItem, bool abExtend = true)
bool Set(uint aulIndex, string asItem, bool abExtend = true)
bool Set(uint aulIndex, cVector avItem, bool abExtend = true)
bool Set(uint aulIndex, cPoint avItem, bool abExtend = true)
bool Set(uint aulIndex, cRotator avItem, bool abExtend = true)
</syntaxhighlight>
Assigns a new value to an indexed item in the list.
 abExtend is optional. If the given index is not valid and abExtend is omitted or true, then the list will be extended to fit the new index, using Extend() with default values. If the given index is not valid and abExtend is false, then the item will not be set.
 Set() returns true if the item was succesfully set. If the item could not be set or if the list could not be extended to fit it, Set() returns false.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
#''bool abExtend'' - Whether to extend the list to fit the new item, if necessary. '''(Optional, default = true)'''
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.

// Example 2:
cListString myListOfStrings;
myListOfInts.Set(3, "three");
myListOfInts.Set(6, "six", true);
myListOfInts.Set(10, "ten", false);
// Setting "three" and "size" succeeded by extending the list.
// Setting "ten" failed because index 10 does not exist, and abExtend is false.
</syntaxhighlight>

====Extend()====
<syntaxhighlight lang="cpp">
bool Extend(uint aulIndex)
</syntaxhighlight>
If given index is not valid, then Extend() adds default items (e.g.: -1, 0.0f, false, "") until the last valid index becomes the given index. Returns false if the list could not be extended to the specified index.
#''uint aulIndex'' - The index which become the new last index, if higher.
<syntaxhighlight lang="cpp">
// Example:
cListString twentyEmptyStrings;
twentyEmptyStrings.Extend(19);
// twentyEmptyStrings now contains... twenty empty strings.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Converting lists===
cListBase and its derived classes provide the following methods for converting lists into other types of collections:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToStringArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a new string representing the whole list, by getting string versions of each item in the list and joining them. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2024-02-11T01:52:02Z

Mrbehemo: Added DefaultValue, Capacity, Fill(), Extend(), AddUnique(), ToString(), ==

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.

There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====Capacity====
<syntaxhighlight lang="cpp">
uint Capacity
</syntaxhighlight>
The read-only integer property Capacity returns the maximum count of items in the list. This will be the default limit, unless one was specified on construction.
<syntaxhighlight lang="cpp">
// Example:
cListInt someList;
someList.Add(1);
uint spaceRemaining = someList.Capacity - someList.Count;
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

====DefaultValue====
<syntaxhighlight lang="cpp">
int DefaultValue
float DefaultValue
double DefaultValue
bool DefaultValue
string DefaultValue
cVector DefaultValue
cPoint DefaultValue
cRotator DefaultValue
</syntaxhighlight>
The read-only property DefaultValue returns the value that this list type uses as a default. The default value is defined by each list class and used instead of a null item. (e.g.: -1, 0.0f, false, "")
<syntaxhighlight lang="cpp">
// Example:
someItem = myList.Pop();
if (someItem == myList.DefaultValue) Debug.Message(1, "Nothing left to pop!");
// The condition succeeds if item returned from the list was the default item, probably because the list was empty.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Equality===

The logical equality operator (double equals sing "==") can be used to compare two lists of the same type, just like with other values. It will return true if the lists contain the same number of items and the coresponding data items in the lists have equal values, or if the two lists both point to the same data.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB;
listA.Add("four");
listA.Add("five");
listA.Add("size");

cListString listC = listB;

bool test1 = listA == listB;
bool test2 = listB == listC;
// test1 will be false because listA and listB contain values that are not equal.
// test2 will be true because listB and listC both point to the same items.
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem, bool abExtend = true)
bool Set(uint aulIndex, float afItem, bool abExtend = true)
bool Set(uint aulIndex, double adItem, bool abExtend = true)
bool Set(uint aulIndex, bool abItem, bool abExtend = true)
bool Set(uint aulIndex, string asItem, bool abExtend = true)
bool Set(uint aulIndex, cVector avItem, bool abExtend = true)
bool Set(uint aulIndex, cPoint avItem, bool abExtend = true)
bool Set(uint aulIndex, cRotator avItem, bool abExtend = true)
</syntaxhighlight>
Assigns a new value to an indexed item in the list.
 abExtend is optional. If the given index is not valid and abExtend is omitted or true, then the list will be extended to fit the new index, using Extend() with default values. If the given index is not valid and abExtend is false, then the item will not be set.
 Set() returns true if the item was succesfully set. If the item could not be set or if the list could not be extended to fit it, Set() returns false.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
#''bool abExtend'' - Whether to extend the list to fit the new item, if necessary. '''(Optional, default = true)'''
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.

// Example 2:
cListString myListOfStrings;
myListOfInts.Set(3, "three");
myListOfInts.Set(6, "six", true);
myListOfInts.Set(10, "ten", false);
// Setting "three" and "size" succeeded by extending the list.
// Setting "ten" failed because index 10 does not exist, and abExtend is false.
</syntaxhighlight>

====Extend()====
<syntaxhighlight lang="cpp">
bool Extend(uint aulIndex)
</syntaxhighlight>
If given index is not valid, then Extend() adds default items (e.g.: -1, 0.0f, false, "") until the last valid index becomes the given index. Returns false if the list could not be extended to the specified index.
#''uint aulIndex'' - The index which become the new last index, if higher.
<syntaxhighlight lang="cpp">
// Example:
cListString twentyEmptyStrings;
twentyEmptyStrings.Extend(19);
// twentyEmptyStrings now contains... twenty empty strings.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Converting lists===
cListBase and its derived classes provide the following methods for converting lists into other types of collections:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToStringArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a new string representing the whole list, by getting string versions of each item in the list and joining them. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

HPL2/HPL2 Helper Scripts/Vectors

2024-02-11T01:46:05Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Vectors.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Vectors.hps" adds support for various vector classes. For beginners or other people not familiar with classes, this is best thought of as new variable types.

At its simplest, vector is a type holds multiple numbers, and is usually used to represent spatial co-ordinates or movement. Some advantages to using a vector over individual numbers is that you can pass the vector as a single argument, or use it in arithmetic as if it was single scalar number. For example:
<syntaxhighlight lang="cpp">
// Example 1 - The basic way:
float fSpeedX = 1.5f;
float fSpeedY = 0.0f;
float fSpeedZ = 0.75f;
float fCurrentX = GetEntityPosX("myEntity");
float fCurrentY = GetEntityPosY("myEntity");
float fCurrentZ = GetEntityPosZ("myEntity");
SetEntityPos("myEntity", fCurrentX + (fSpeedX * afStep), fCurrentY + (fSpeedY * afStep), fCurrentZ + (fSpeedZ * afStep));

// Example 2 - The Helper Scripts way:
cVector vSpeed = new cVector(1.5f, 0.0f, 0.75f);
cVector vCurrent = GetEntityPosVec("myEntity");
SetEntityPosVec("myEntity", vCurrent + (vSpeed * afStep));
</syntaxhighlight>

These two examples have the same effect, but with much simpler code.

Various methods are provided, in both the vector classes and in Math, for working with vectors; for example, to find out the length of a line, working out rotations, plotting paths and more.

===Vector types===
Available vector classes:
<code>cVector</code>, <code>cPoint</code>, <code>cRotator</code>, <code>cBezier</code>, <code>cSpline</code>

===The basics===
Declare a vector like any other variable, and use its various properties, operations and methods list on this page to work with it. For example:
<syntaxhighlight lang="cpp">
cVector myVector; // Declares a new cVector, called myVector. By default it's a 3d vector.
cVector my2dVector(2); // Declares a new cVector, set up to have 2 dimensions.
cVector myVector.X = 2.0f; // Assigns the value 2.0f to the X component of myVector.
</syntaxhighlight>
The cPoint and cRotator classes work similarly. (A cPoint is a vector containing integers instead of floats, and a cRotator is a vector intended for working with pitch-yaw-roll rotations.

===Component properties===
The simplest way to access the components of a 2d or 3d vector is through the named properties. A 2d or 3d cVector provides X and Y, or X, Y and Z properties. cRotator has Pitch, Yaw and Roll. See the notes below for more details on each class.

===Indices===
Like arrays, you can ''get'' the items in the vector using an index operator, e.g. myVector[0], myVector[1], myVector[2] are the same as the X, Y and Z properties. However, ''unlike arrays'', this is '''read-only'''.

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
cRotator inherits from cVector. Advanced users who want to make their own derived vector types are advised to read over the cVector definition and derived class definitions to see how they inherit.

cVector and cPoint can both be used for 2d or 3d vectors. The vector classes are designed to be agnostic of dimensionality. The maximum number of dimensions for all vector classes is defined by ulVectorDimMax. The default value is 16, but an advanced user may want to edit that value. cVector and it's derived classes can have any number of dimensions from 0 to, in theory, 65535, although either extreme would be ridiculous. Using a maximum larger than 65535 could cause problems.

Arithmetic, and some methods, can work with differently dimensioned vectors. For example <code>a[X,Y,Z] + b[X,Y]</code> has the same effect as <code>a[X,Y,Z] + b[X,Y,0]</code>.

=cVector=
The cVector class defines a type that contains a series of float values, typically used to represent a spatial location or movement.

==Behaviours==
cVectors are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cVector myVector;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cVector myVector; // Makes a 3d vector
cVector myVector = cVector(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cVector myVector = cVector(3); // Makes a 3d vector

cVector myVector = cVector(2); // Makes a 2d vector
cVector myVector = cVector(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cVector provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
float X
</syntaxhighlight>
The float property X provides access to the first component in the cVector (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.X;
vMyVector.X = 1.0f;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
float Y
</syntaxhighlight>
The float property Y provides access to the second component in the cVector (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Y;
vMyVector.Y = 1.0f;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
float Z
</syntaxhighlight>
The float property Z provides access to the third component in the cVector (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.Z;
vMyVector.Z = 1.0f;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
float W
</syntaxhighlight>
The float property W provides access to the fourth component in the cVector (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.W;
vMyVector.W = 1.0f;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cVector. The dimension of the cVector can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyVector.Dimension >=3) vMyVector.Z = 0.0f;
// The condition succeeds if the cVector has at least three components, and then the value of the 3rd component is assigned 0.0f.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cVector. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
float fMyFloat = vMyVector[vMyVector.LastIndex];
// The float fMyFloat is assigned whatever value is found in the final component of the cVector.
</syntaxhighlight>

==Operators==

Some '''arithmetic''' operators have been implemented for '''a cVector with another cVector''':
<syntaxhighlight lang="cpp"> + - = += -= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cVector with a float''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

The '''multiplication''' operator <code>*</code> used with a cVector on another cVector will return the '''dot product''' of the two vectors, as a float.

The '''equality''' operator <code> == </code> checks for an exact match between two cVectors. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cVector provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, float afValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''float afValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetIndex(1, 3.0f);
vMyVector.Y = 3.0f;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir2d(dirLeft);
// vMyVector becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cVector into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyVector.SetDir3d(dirLeft);
// vMyVector becomes 1,0,0
</syntaxhighlight>

===Getting values===
cVector provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
float GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyVector.GetIndex(2);
fMyFloat = vMyVector.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cVector provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
float Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a float. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cVector vMyRectangle = cVector(10.0f, 15.0f);
float fMyHypotenuse = vMyRectangle.Length();
// fMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
float LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cVector Normal()
</syntaxhighlight>
Calculates the normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal() * fSpeed;
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of exactly fSpeed.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become 1.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Strings from cVector===
cVector provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cVector" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cVector by one, and adds the given float as a new component.
bool Append(cVector avValues) // Increases the dimension of this cVector to accomodate the given cVector, and appends its components.
const float[]@ ReadArray() // Returns a handle to the cVector's component array data.
</syntaxhighlight>

=cPoint=
The cPoint class defines a vector type that contains a series of int values, typically used to represent a location or movement on a grid, or pixels.

==Behaviours==
cPoints are declared similarly to a data type variable:
<syntaxhighlight lang="cpp">
cPoint myPoint;
</syntaxhighlight>

The default constructor makes an empty 3d vector:
<syntaxhighlight lang="cpp">
cPoint myPoint; // Makes a 3d vector
cPoint myPoint = cPoint(); // Makes a 3d vector
</syntaxhighlight>

You can make an empty vector with a specific dimension (the number of components) by passing an integer to the constructor:
<syntaxhighlight lang="cpp">
cPoint myPoint = cPoint(3); // Makes a 3d vector

cPoint myPoint = cPoint(2); // Makes a 2d vector
cPoint myPoint = cPoint(4); // Makes a 4d vector
</syntaxhighlight>

A vector can be initialised with any number dimension up to ulVectorDimMax (default 16).

==Properties==
cPoint provides the following public properties:

====X====
<syntaxhighlight lang="cpp">
int X
</syntaxhighlight>
The integer property X provides access to the first component in the cPoint (provided it has at least one component).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.X;
vMyPoint.X = 1;
</syntaxhighlight>

====Y====
<syntaxhighlight lang="cpp">
int Y
</syntaxhighlight>
The integer property Y provides access to the second component in the cPoint (provided it has at least two components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Y;
vMyPoint.Y = 1;
</syntaxhighlight>

====Z====
<syntaxhighlight lang="cpp">
int Z
</syntaxhighlight>
The integer property Z provides access to the third component in the cPoint (provided it has at least three components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.Z;
vMyPoint.Z = 1;
</syntaxhighlight>

====W====
<syntaxhighlight lang="cpp">
int W
</syntaxhighlight>
The integer property W provides access to the fourth component in the cPoint (provided it has at least four components).
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.W;
vMyPoint.W = 1;
</syntaxhighlight>

====Dimension====
<syntaxhighlight lang="cpp">
uint Dimension
</syntaxhighlight>
The read-only integer property Dimension returns the number of components in the cPoint. The dimension of the cPoint can be set by the constructor or, see also: Resize().
<syntaxhighlight lang="cpp">
// Example:
if (vMyPoint.Dimension >=3) vMyPoint.Z = 0;
// The condition succeeds if the cPoint has at least three components, and then the value of the 3rd component is assigned 0.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the index of the last component in the cPoint. This is the same as Dimension - 1.
<syntaxhighlight lang="cpp">
// Example:
int fMyInt = vMyPoint[vMyPoint.LastIndex];
// The int fMyInt is assigned whatever value is found in the final component of the cPoint.
</syntaxhighlight>

==Operators==

Note: the results of division operations with ints maybe truncated. That is, in integer calculations, 1 / 2 = 0.

Some '''arithmetic''' operators have been implemented for '''a cPoint with another cPoint''':
<syntaxhighlight lang="cpp"> + - = += -= </syntaxhighlight>

Additional '''arithmetic''' operators have been implemented for '''a cPoint with an int''':
<syntaxhighlight lang="cpp"> + - * / += -= *= /= </syntaxhighlight>

The '''multiplication''' operator <code>*</code> used with a cPoint on another cPoint will return the '''dot product''' of the two vectors, as a truncated int.

The '''equality''' operator <code> == </code> checks for an exact match between two cPoints. '''Comparison''' operators <code> > >= < <= </code> compare the '''square length''' of the vectors.

The '''index''' operator <code> myVector[i] </code> allows read-only access to the vector's components by index.

The '''assignment''' operator <code> = </code> assigns a new value by duplicating the components. This may also '''resize''' the dimension of the vector.

==Methods==

===Setting values===
cPoint provides the following methods for assigning values to the vector components: (See also: X,Y,Z,W properties)

====SetIndex()====
<syntaxhighlight lang="cpp">
bool SetIndex(uint aulIndex, int alValue)
</syntaxhighlight>
Assigns a new value to a component by index. E.g., the X component is at index 0, Y is index 1, etc.. Returns false if index is outside of the dimension of the vector, or true if it was successfully set.
#''uint aulIndex'' - The index to set with a new value.
#''int alValue'' - The value to set at the index.
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetIndex(1, 3);
vMyPoint.Y = 3;
// These two techniques have the same outcome.
</syntaxhighlight>

====SetDir2d()====
<syntaxhighlight lang="cpp">
bool SetDir2d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 2d vector pointing in that direction.

Uses typical screen coordinate directions, where up is -y, right is +x. If forward is given then that is considered to be right (+x).
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir2d(dirLeft);
// vMyPoint becomes -1,0
</syntaxhighlight>

====SetDir3d====
<syntaxhighlight lang="cpp">
bool SetDir3d(enumOrthoDir aDirection)
</syntaxhighlight>
Given an enumOrthoDir option, this converts the existing cPoint into a 3d vector pointing in that direction.

Uses HPL2's "right-handed, x=left" coordinate system, so the forward direction is considered to be 0,0,1. Right is -1,0,0 and up is 0,1,0.
#''enumOrthoDir aDirection'' - Can be dirForward, dirBackward, dirLeft, dirRight, dirUp or dirDown
<syntaxhighlight lang="cpp">
// Example:
vMyPoint.SetDir3d(dirLeft);
// vMyPoint becomes 1,0,0
</syntaxhighlight>

===Getting values===
cPoint provides the following method for retrieving values from the vector components: (See also: X,Y,Z,W properties)

====GetIndex()====
<syntaxhighlight lang="cpp">
int GetIndex(uint aulIndex)
</syntaxhighlight>
Retrieves a component by index. E.g., the X component is at index 0, Y is index 1, etc.
#''uint aulIndex'' - The index whose value to get.
<syntaxhighlight lang="cpp">
// Example:
fMyInt = vMyPoint.GetIndex(2);
fMyInt = vMyPoint.Z;
// These two techniques have the same outcome.
</syntaxhighlight>

===Length===
cPoint provides the following methods for working with vector length:

====Length()====
<syntaxhighlight lang="cpp">
int Length()
</syntaxhighlight>
Returns the euclidean length of the vector as a truncated int. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
cPoint vMyRectangle = cPoint(10, 15);
int lMyHypotenuse = vMyRectangle.Length();
// lMyHypotenuse becomes the length of the diagonal line across a rectangle 10m by 15m.
</syntaxhighlight>

====LengthSqr()====
<syntaxhighlight lang="cpp">
int LengthSqr()
</syntaxhighlight>
Returns the squared length of the vector, which can be more efficient than calculating the actual length in some use cases, e.g. when you only need to compare two lengths without knowing the exact values. (See also: Math.Length())
<syntaxhighlight lang="cpp">
// Example:
bool bIsVecALonger = vVecA.LengthSqr() > vVecB.LengthSqr();
// bIsVecALonger becomes true if vVecA is longer than vVecB, without calculating the final lengths.
</syntaxhighlight>

====Normal()====
<syntaxhighlight lang="cpp">
cPoint Normal()
</syntaxhighlight>
Calculates the truncated integer normal of this vector and returns it as a copy. This vector is not changed. The normal vector points in the same direction, but has a length of approximately one, while the components remain whole numbers.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection.Normal();
// If vDirection is a vector of unknown length pointing in some direction, this would set vVelocity to be a vector pointing in the same direction, but with a length of approximately one.
</syntaxhighlight>

====Normalize()====
<syntaxhighlight lang="cpp">
void Normalize()
</syntaxhighlight>
Normalizes a vector in place. This vector becomes the normal vector, and the original values are forgotten. The normal vector points in the same direction, but has a length of approximately one.
<syntaxhighlight lang="cpp">
// Example:
vVelocity = vDirection;
vVelocity.Normalize(); // Length of vVelocity has now become approximately one.
vVelocity *= 3.0f;
// This example has the same result as the previous one, for Normal().
</syntaxhighlight>

===Strings from cPoint===
cPoint provides the following methods for converting vectors to strings:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the vector as a string.
 If the dimension is 2, the format "(x=_, y=_)" is used.
 If the dimension is 3, the format "(x=_, y=_, z=_)" is used.
 If the dimension is 0, the string "empty cPoint" is returned.
 For any other dimension, ToStringAsIndices() is called instead.
 

====ToStringAsIndices()====
<syntaxhighlight lang="cpp">
string ToStringAsIndices()
</syntaxhighlight>
Returns the components of the vector as a string, in the format "([0]=_, [1]=_, [2]=_ ...)".
 

===Advanced===
The following methods exist for advanced users and should be used with caution:
<syntaxhighlight lang="cpp">
bool Resize(uint aulNewDim) // Changes the dimension of the vector.
bool Append(float afValue) // Increases the dimension of this cPoint by one, and adds the given float as a new component.
bool Append(cPoint avValues) // Increases the dimension of this cPoint to accomodate the given cPoint, and appends its components.
const int[]@ ReadArray() // Returns a handle to the cPoint's component data array.
</syntaxhighlight>

=cRotator=
The cRotator class defines a type that contains a series of float values, intended to represent an angular orientation, or a rotation. cRotator inherits from cVector, but also defines some properties and methods specific to working with rotation.

==Behaviours==
There are two ways to assign the pitch, yaw and roll values in the constructor.

1. The angle values can be set directly in the constructor using degrees or radians. An optional enumAngleUnits is used to specify whether using degrees. The default is radians.
<syntaxhighlight lang="cpp">
// Initialising angles in degrees:
cRotator(pitchDegrees, yawDegrees, rollDegrees, angleDegrees)

// Initialise the angles in radians
cRotator(pitchRadians, yawRadians, rollRadians)
cRotator(pitchRadians, yawRadians, rollRadians, angleRadians)

// These two rotators are equivalent:
cRotator myDegrees = cRotator(90.0f, 180.0f, 45.0f, true);
cRotator myRadians = cRotator(Math.Pi, Math.Tau, Math.Pi / 2.0f);
</syntaxhighlight>

2. The angle values can be set in the constructor using an enumOrthoDir option. enumOrthoDir can be dirForward, dirBackward, dirLeft, dirRight, dirUp, or dirDown.
<syntaxhighlight lang="cpp">
cRotator yawRight = cRotator(dirRight);
cRotator pitchDown = cRotator(dirDown);
</syntaxhighlight>

==Properties==
The angle values can be set with the Pitch, Yaw and Roll properties:
<syntaxhighlight lang="cpp">
myRotator.Pitch = Math.Pi / 2.0f;
</syntaxhighlight>

The pitch, yaw and roll properties are treated as radians by default. To specify degrees or radians explicitly, the pitchDeg, yawDeg, rollDeg, and pitchRad, yawRad, rollRad properties can be used, e.g.:
<syntaxhighlight lang="cpp">
myRotator.YawDeg = 180;
myRotator.RollRad = Math.Pi * 3.0f;
</syntaxhighlight>

Internally the cRotator class stores angle values as radians between negative and positive Pi. (Equivalent to -180 degrees to 180 degrees.) Angles outside of this range are wrapped around. E.g.:
<syntaxhighlight lang="cpp">
cRotator rotation = cRotator(0.0f, 90.0f, 0.0f, true);
rotation += cRotator(0.0f, 120.0f, 0.0f, true);
// rotation is now (degrees) 0.0f, -150.0f, 0.0f
</syntaxhighlight>

In this example, "rotation" is initialised with 90d yaw, and then rotated a further
120d clockwise. Rather than 210d clockwise, the resulting yaw is 150 anti-clockwise (-150);

====Pitch====
<syntaxhighlight lang="cpp">
float Pitch
float PitchRad
float PitchDeg
</syntaxhighlight>
The float properties Pitch and PitchRad provide access to the pitch component in radians. PitchDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Pitch;
vMyRotator.PitchDeg = 90.0f;
</syntaxhighlight>

====Yaw====
<syntaxhighlight lang="cpp">
float Yaw
float YawRad
float YawDeg
</syntaxhighlight>
The float properties Yaw and YawRad provide access to the pitch component in radians. YawDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Yaw;
vMyRotator.YawDeg = 90.0f;
</syntaxhighlight>

====Roll====
<syntaxhighlight lang="cpp">
float Roll
float RollRad
float RollDeg
</syntaxhighlight>
The float properties Roll and RollRad provide access to the pitch component in radians. RollDeg provides access to the pitch component in degrees.
<syntaxhighlight lang="cpp">
// Example:
fMyFloat = vMyRotator.Roll;
vMyRotator.RollDeg = 90.0f;
</syntaxhighlight>

==Methods==
In addition to methods inherited from cVector, cRotator provides the following methods:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
string ToStringRad()
</syntaxhighlight>
Returns the components of the vector as radians in a string with the format "(p=_, y=_, r=_)(rad)".
 

====ToStringDeg()====
<syntaxhighlight lang="cpp">
string ToStringDeg()
</syntaxhighlight>
Returns the components of the vector as degrees in a string with the format "(p=_, y=_, r=_)(deg)".
 

=cBezier=

The cBezier class defines a curved line in space, with a couple of basic functions. Technically it is a cubic bezier defined by 4 points: a start, an end, and two control points for influencing the curve. It can also roughly approximate a quadratic bezier if constructed with only one control point.

==Behaviours==
cBezier has four constructors:

<syntaxhighlight lang="cpp">
cBezier(cVector avStart, cVector avCtrl1, cVector avCtrl2, cVector avEnd) // Creates a cubic bezier with two control points.
cBezier(cVector avStart, cVector avCtrl, cVector avEnd) // Creates bezier approximating a quadratic bezier.
cBezier(cVector avStart, cVector avEnd) // Creates a bezier that behaves like a straight line.
cBezier() // Creates a bezier that starts and ends at 0,0,0, with zero length.
</syntaxhighlight>

==Properties:==
To access the internal vector positions in the bezier, you can use the properties: Start, End, CtrlStart and CtrlEnd.
<syntaxhighlight lang="cpp">
cBezier manualBezier;
cVector someLocation = cVector(10.0f, 11.0f, 12.0f);
manualBezier.Start = someLocation;
manualBezier.End = someLocation * 1.5f;
</syntaxhighlight>

====Start====
<syntaxhighlight lang="cpp">
cVector Start
</syntaxhighlight>
The cVector property Start can be used to get or set the start point of the curve with a 3d cVector.

====End====
<syntaxhighlight lang="cpp">
cVector End
</syntaxhighlight>
The cVector property End can be used to get or set the end point of the curve with a 3d cVector.

====CtrlStart====
<syntaxhighlight lang="cpp">
cVector CtrlStart
</syntaxhighlight>
The cVector property CtrlStart can be used to get or set the first control point of the curve with a 3d cVector.

====CtrlEnd====
<syntaxhighlight lang="cpp">
cVector CtrlEnd
</syntaxhighlight>
The cVector property CtrlEnd can be used to get or set the second control point of the curve with a 3d cVector.

==Methods==
cBezier provides the following methods:

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMyBezier.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the curve.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the curve from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMyBezier.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the curve at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the curve.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the components of the bezier as a string, including the x,y,z components of all four vector positions.

=cSpline=

The cSpline class defines an array of Beziers that can be treated like a continuous path made of multiple curved segments. Internally cSpline is a cBezier array of a fixed maximum size (default = 16). The cSpline can be initialised using existing beziers, or with a single curve defined by args in the constructor.

For further control over how the curve is built, the cSpline can be declare as empty with segments added afterwards. Segments can be added to the spline either as whole cBezier segments using AddSegment(), or by adding one cVector point at a time using AddPoint().

With the AddPoint() method, the spline is defined by providing the positions it should move through as individual points in space. Specific tangents can be provided (forward direction and scale) for each point, but are optional. When the final point is added, abLast should be specified as true to finish the spline and apply automatic tangents where needed. The automatic tangents make sure that path through each point is smooth, unless specific tangents were specified through AddPoint().

Alternatively, with the AddSegment() method, the spline can be defined by providing each segment as a Bezier. The end of the previous segment will be updated to match the new one. (This is not quite the same as passing an array of Beziers to the constructor, as in that case the constructor will not attempt to match the end points, and they will not be smooth or even continuous unless defined that way by the script.)

The spline does not have constant velocity. That is to say, each segment has an equal share of the "time", regardless of the size of the segment, and within each segment the control points can cause acceleration. Easing can be effected by varying the size of the segments.

==Behaviours==
cSpline has seven constructors in total, with various options for initialising a curve.

===Constructing empty splines===
If the cSpline should start empty, ready for AddSegment() or AddPoint(), one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline() // Creates an empty spline with a maximum size of 16 bezier segments.
cSpline(uint aulSegments) // Creates an empty spline with capacity for the number of bezier segments specified by aulSegments.
</syntaxhighlight>

===Constructing with cBezier===
If the cSpline should be populated with one or more existing bezier curves, one of the following constructors should be used:
<syntaxhighlight lang="cpp">
cSpline(cBezier aSegmentsArray) // Takes an existing cBezier array and uses that to populate the new spline.
cSpline(cBezier@ ahBezier) // Uses a reference to an existing cBezier to populate the new spline with a single segment.
</syntaxhighlight>

===Constructing with cVector===
Finally, if the cSpline should be populated a curve or line defined by cVector arguments, one of these constructors will help:
<syntaxhighlight lang="cpp">
cSpline(cVector avStart, cVector avCtrlStart, cVector avCtrlEnd, cVector avEnd)
// Takes four vector positions and builds a cubic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avCtrl, cVector avEnd)
// Takes three vector positions and builds a approximation of a quadratic bezier to populate the new spline with a single segment.

cSpline(cVector avStart, cVector avEnd)
// Takes two vector positions and populate the new spline with a single segment in the form of a straight line between two points.
</syntaxhighlight>

==Methods==
cBezier provides the following methods:

====AddSegment()====
<syntaxhighlight lang="cpp">
bool AddSegment(cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Appends a bezier onto the spline as new segment. Returns false if the spline is already full, or true if it was successfully added.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment will be adjusted to connect to the start point and entrance tangent of the new one.
#''cBezier ahSegment'' - A bezier to be appended to the spline.
#''bool abSnap'' - Whether to adjust the previous segment to connect to the new one. (Optional, default = true)

====UpdateSegment()====
<syntaxhighlight lang="cpp">
bool UpdateSegment(uint aulIndex, cBezier ahSegment, bool abSnap = true)
</syntaxhighlight>
Updates an existing segment by index, replacing it with a new bezier. Returns false if the segment does not already exist, or true if it was successfully updated.
 abSnap is optional. If omitted, it defaults to true. If abSnap is true then the end point and exit tangent of the previous segment, and the start point and entrance tangent of the next segment will be adjusted to connect to the updated segment.
#''uint aulIndex'' - The index of the segment to be replaced.
#''cBezier ahSegment'' - A bezier to be replace the bezier at the given index. to the spline.
#''bool abSnap'' - Whether to adjust the previous and next segments to connect to the updated one. (Optional, default = true)

====AddPoint()====
<syntaxhighlight lang="cpp">
bool AddPoint(bool abLast = false, cVector avNextPosition, cVector avNextTangent)
bool AddPoint(bool abLast = false, cVector avNextPosition)
</syntaxhighlight>
Appends a position to the end of the spline. Returns false if the spline is already full, or true if it was successfully added.
 avNextTangent is optional and can be omitted. It specifies the tangent as the velocity (direction and scale) of the spline at the new point. If omitted, no tangent is used at this time, but once you have finished adding points, abLast = true should be used and automatic tangents will be applied at that time.
 The automatic tangents are only applied to points where no tangent was given, and only once the spine is marked as "finished" by using abLast = true;
#''bool abLast'' - Whether this is the last point to be added. (Optional, default = false)
#''cVector avNextPosition'' - A position in space to add to the spline.
#''cVector avNextTangent'' - The forward velocity of the spline as it passes through the new position. (Optional, default = auto)

====GetPoint()====
<syntaxhighlight lang="cpp">
cVector GetPoint(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns the position at that point. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the position of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.33f;
cVector vLocationOnCurve = vMySpline.GetPoint(vProgressOnCurve);
// vLocationOnCurve becomes the position in space that is 33% of the journey along the spline.
</syntaxhighlight>

====GetTangent()====
<syntaxhighlight lang="cpp">
cVector GetTangent(float afT)
</syntaxhighlight>
Given a point on the entire spline from 0.0f to 1.0f, this returns a normal vector that approximates the forward direction of the curve at that position. The float value is known as the "time" on the curve. The velocity is not constant: the control points can cause acceleration in how the movement is calculated.
#''float afT'' - The time on the curve (0.0 - 1.0) to get the tangent of.
<syntaxhighlight lang="cpp">
float vProgressOnCurve = 0.66f;
cVector vDirectionOnCurve = vMySpline.GetTangent(vProgressOnCurve);
// vDirectionOnCurve becomes the forward direction of the spline at the point of 66% through the journey along it.
</syntaxhighlight>

====GetApproxLength()====
<syntaxhighlight lang="cpp">
float GetApproxLength(enumLengthType aSquaredOption = lengthFinal)
</syntaxhighlight>
Estimates the approximate length of the entire spline.
#''enumLengthType aSquaredOption'' - Can be lengthFinal or lengthSquared. (Optional, default = lengthFinal)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a string describing the spline, including the x,y,z components of its start and end points, and the number of segments.

__FORCETOC__

HPL2/HPL2 Helper Scripts/GameVars

2024-02-11T01:14:01Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_GameVars.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script file "HelperScripts_GameVars.hps" builds on top of the normal saved game global and local variable wrappers, adding the ability to save more variable types to the save game file, including vectors and lists/arrays.
<syntaxhighlight lang="cpp">
// The basic way:
SetLocalVarInt("myInteger", 99);
// The Helper Scripts way:
GameVars.SetInt(varLocal, "myInteger", 99);
</syntaxhighlight>

GameVars variables work in a similar way to the normal saved game global and local variable wrappers, with three differences:

===Scope===
Firstly, instead of separate functions for local and global variables, GameVars uses an optional argument to specify the scope. Each of the GameVars methods has an optional enumVarScope, which can be either '''varLocal''' or '''varGlobal'''. If omitted, the '''default is scope is global'''. For example:
<syntaxhighlight lang="cpp">
GameVars.SetInt(varLocal, "some_number", 99); // Does the same thing as SetLocalVarInt("some_number", 99);
GameVars.SetInt(varGlobal, "some_number", 99); // Does the same thing as SetGlobalVarInt("some_number", 99);
GameVars.SetInt("some_number", 99); // Does the same thing as SetGlobalVarInt("some_number", 99);
</syntaxhighlight>
The scope could even be used variably, for example:
<syntaxhighlight lang="cpp">
enumVarScope scopeForRadioMessages = varLocal;

// After interacting with the radio booster:
scopeForRadioMessages = bRadioBoosterActived ? varGlobal : varLocal;

// On sending a radio message:
GameVars.SetString(scopeForRadioMessages, "radioMessage", "SendHelp");

// This example imagines a scenario where the radioMessage state copied to other levels only while the radio booster is active.
</syntaxhighlight>

===New Types===
Secondly, '''additional variable types''' are available. As well as the normal int, float and string game variables, GameVars has methods for storing and retrieving variables as bool, cVector, cPoint and cRotator. For example:
<syntaxhighlight lang="cpp">
GameVars.SetBool("myBoolean", true);
if (GameVars.GetBool("myBoolean"))
{
GameVars.SetVector("myVector2", cVector(0.0f, 0.0f));
}
</syntaxhighlight>

===Lists===
And thirdly GameVars can store '''indexed lists''' of variables, in the style of an '''array or linked list'''. For example, SetListInt() can be passed an array of ints or a cListInt. The return value of GetListInt is a cListInt list that can be assigned to a list variable, or used with the index operator directly. For example:
<syntaxhighlight lang="cpp">
bool[] myArrayOfBools = { true, true, false, false, false };
GameVars.SetListBool("myStoredBools", myArrayOfBools); // Stores the bools from the array as a game variable list.
GameVars.SetListBool("myStoredBools", 9, true); // Sets the value of the bool at index 9 in the stored list.

cListString myStringList = GameVars.GetListString("myStoredStrings"); // Retrieves the stored list of strings and assigns it to the cListString.

string aSingleString = GameVars.GetListString("myStoredStrings", 3); // Retrieves the string at index 3 of the stored list and assigns it to the string.
string anotherString = GameVars.GetListString("myStoredStrings")[3]; // Retrieves the string at index 3 of the stored list and assigns it to the string.

if (GameVars.GetListBool(varLocal, "myStoredBools")[0]) // The condition succeeds if the first bool in the stored list is true.
</syntaxhighlight>

Imporant Note 1: GameVars variable names cannot contain the @ symbol, as it is reserved by GameVars.
Imporant Note 2: GameVars names cannot be reliably re-used between types.
If a name is used containing @, or the same name is used for two differently typed GameVars variables, then it might simply not work or it might return erroneous results.

Behind the scenes, GameVars uses one or more ints or floats to store the new types.
The double and uint types are not provided for, as they could lose precision when stored as floats or int. Use the float and int methods explicitly instead.

=GameVars=

==Behaviours==
"HelperScripts_GameVars.hps" declares an object called '''GameVars''', of the new script class cGameVars. To access its methods, just use "GameVars." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
GameVars.SetBool(varLocal, "someBoolean", false);
</syntaxhighlight>

==Properties==
GameVars has no public properties.

==Methods==
GameVars provides the following methods:

===Single Variables===

====Set...()====
<syntaxhighlight lang="cpp">
void SetInt(enumVarScope aScopeOption, string asName, int alValue)
void SetFloat(enumVarScope aScopeOption, string asName, float afValue)
void SetString(enumVarScope aScopeOption, string asName, string asValue)
void SetBool(enumVarScope aScopeOption, string asName, bool abValue)
void SetVector(enumVarScope aScopeOption, string asName, cVector avhValue)
void SetRotator(enumVarScope aScopeOption, string asName, cRotator avhValue)
void SetPoint(enumVarScope aScopeOption, string asName, cPoint avhValue)
</syntaxhighlight>
Stores a single game variable with the given value and name.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the game variable to set.
#''int alValue, float afValue, string asValue, bool abValue, cVector avhValue, cRotator avhValue, or cPoint avhValue'' - A value of the appropriate type to be set as the named game variable.
<syntaxhighlight lang="cpp">
// Example:
GameVars.SetString(varLocal, "itemName", "bucket");
GameVars.SetVector(varGlobal, "puzzleDir", cVector(1.0f, 0.0f, 0.0f));
GameVars.SetBool("doorOpen", true);
// The string game var itemName is set to "bucket" in the local scope (for this level only).
// The vector game var puzzleDir is set to 1,0,0 in the global scope (for all levels).
// The bool game var doorOpen is set to true in the global scope (for all levels).
</syntaxhighlight>

====Get...()====
<syntaxhighlight lang="cpp">
int GetInt(enumVarScope aScopeOption, string asName)
float GetFloat(enumVarScope aScopeOption, string asName)
string GetString(enumVarScope aScopeOption, string asName)
bool GetBool(enumVarScope aScopeOption, string asName)
cVector GetVector(enumVarScope aScopeOption, string asName)
cRotator GetRotator(enumVarScope aScopeOption, string asName)
cPoint GetPoint(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Retrieves a single game variable with the given name and returns it as the appropriate variable type.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the game variable to get.
<syntaxhighlight lang="cpp">
// Example 1:
string itemName GameVars.GetString(varLocal, "itemName");
// The script var itemName is assigned the value from the local game var with the same name.

// Example 2:
vHalfSpeed = GameVars.GetVector("savedSpeed") / 2.0f;
// The script vector var vHalfSpeed is assigned with the vector retrieved from the global game var savedSpeed, divided by two.

// Example 3:
if(GameVars.GetBool("doorOpen", true) DoStuff();
// The condition succeeds if the global game var doorOpen is retrieved as true.
</syntaxhighlight>

====Add...()====
<syntaxhighlight lang="cpp">
void AddInt(enumVarScope aScopeOption, string asName, int alValue)
void AddFloat(enumVarScope aScopeOption, string asName, float afValue)
void AddVector(enumVarScope aScopeOption, string asName, cVector avhValue)
void AddRotator(enumVarScope aScopeOption, string asName, cRotator avhValue)
void AddPoint(enumVarScope aScopeOption, string asName, cPoint avhValue)
</syntaxhighlight>
Updates a stored numeric game variable with the given name by adding the given value arithmetically. To subtract, use a negative value. Not to be confused with AddString() (appends text) or AddListItem...() (appends an item to a list).
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the game variable to add to.
#''int alValue, float afValue, cVector avhValue, cRotator avhValue, or cPoint avhValue'' - A value of the appropriate type to be add to the named game variable.
<syntaxhighlight lang="cpp">
// Example 1:
GameVars.AddFloat("runningTotal", 3.5f);
// The global float game var runningTotal increases by 3.5.

// Example 2:
GameVars.AddPoint(varLocal, "gridPos" cPoint(0, -1, 0));
// The local point game var gridPos decreases by 1 in the y axis.
</syntaxhighlight>

====AddString()====
<syntaxhighlight lang="cpp">
void AddString(enumVarScope aScopeOption, string asName, string asName)
</syntaxhighlight>
Updates a stored string game variable with the given name by appending the given text.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the string game variable to append to.
#''string asValue'' - A string to append to the named game variable.
<syntaxhighlight lang="cpp">
// Example:
GameVars.AddString("message", " Goodbye!");
// The global string game var message is appended with the second string.
</syntaxhighlight>

====NotBool()====
<syntaxhighlight lang="cpp">
void NotBool(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Updates a stored bool game variable by inverting it.
If the stored bool is true, it becomes false and vice versa.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the bool game variable to update.
<syntaxhighlight lang="cpp">
// Example:
GameVars.SetBool(varLocal, "flipflop", false);
GameVars.NotBool(varLocal, "flipflop");
// The local bool game var flipflop is first set to false but then becomes true.
</syntaxhighlight>

====AndBool()====
<syntaxhighlight lang="cpp">
void AndBool(enumVarScope aScopeOption, string asName, bool abValue)
</syntaxhighlight>
Updates a stored bool game variable by combining it with the given value, using AND logic.
The stored bool will be true if both itself and abValue are true.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the bool game variable to update.
#''bool abValue'' - The bool value to combine with the stored value.
<syntaxhighlight lang="cpp">
// Example:
GameVars.SetBool(varGlobal, "flipflop", false);
GameVars.AndBool(varGlobal, "flipflop", true);
// The global bool game var flipflop stays false.
</syntaxhighlight>

====OrBool()====
<syntaxhighlight lang="cpp">
void OrBool(enumVarScope aScopeOption, string asName, bool abValue)
</syntaxhighlight>
Updates a stored bool game variable by combining it with the given value, using OR logic.
The stored bool will be true if either itself or abValue are true.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the bool game variable to update.
#''bool abValue'' - The bool value to combine with the stored value.
<syntaxhighlight lang="cpp">
// Example:
GameVars.SetBool(varGlobal, "flipflop", false);
GameVars.AndBool(varGlobal, "flipflop", true);
// The global bool game var flipflop becomes true.
</syntaxhighlight>

====GetIntAsUint()====
<syntaxhighlight lang="cpp">
uint GetIntAsUint(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Retrieves a stored int game variable and returns it as a uint. If the stored int is negative, the returned uint will be 0.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the int game variable to retrieve.

====SetIntAsUint()====
<syntaxhighlight lang="cpp">
void SetIntAsUint(enumVarScope aScopeOption, string asName, uint aulValue)
</syntaxhighlight>
Takes a uint argument and stores it as an int. This is the same as SetInt(), except that it explicitly casts the uint to int, which avoids type conversion warnings.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the int game variable to set.
#''uint aulValue'' - The uint value to be stored as an int.

====GetFloatAsDouble()====
<syntaxhighlight lang="cpp">
double GetFloatAsDouble(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Retrieves a stored float game variable and returns it as a double.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the int game variable to retrieve.

===Lists===

====SetList...()====
<syntaxhighlight lang="cpp">
void SetListInt(enumVarScope aScopeOption, string asName, cListInt alValues)
void SetListFloat(enumVarScope aScopeOption, string asName, cListFloat afValues)
void SetListString(enumVarScope aScopeOption, string asName, cListString asValues)
void SetListBool(enumVarScope aScopeOption, string asName, cListBool abValues)
void SetListVector(enumVarScope aScopeOption, string asName, cListVector avhValues)
void SetListRotator(enumVarScope aScopeOption, string asName, cListRotator avhValues)
void SetListPoint(enumVarScope aScopeOption, string asName, cListPoint avhValues)

void SetListInt(enumVarScope aScopeOption, string asName, int[] alValues)
void SetListFloat(enumVarScope aScopeOption, string asName, float[] afValues)
void SetListString(enumVarScope aScopeOption, string asName, string[] asValues)
void SetListBool(enumVarScope aScopeOption, string asName, bool[] abValues)
void SetListVector(enumVarScope aScopeOption, string asName, cVector[] avhValues)
void SetListRotator(enumVarScope aScopeOption, string asName, cRotator[] avhValues)
void SetListPoint(enumVarScope aScopeOption, string asName, cPoint[] avhValues)
</syntaxhighlight>
Stores a list or array of game variables under a single name.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the game variable to store as a list.
#''cListInt alValues, cListFloat afValues, cListString asValues, cListBool abValues, cListVector avhValues, cListRotator avhValues, cListPoint avhValues
int[] alValues, float[] afValues, string[] asValues, bool[] abValues, cVector[] avhValues, cRotator[] avhValues, or cPoint[] avhValues'' - A value of the appropriate type to be set as the named game variable.
<syntaxhighlight lang="cpp">
// Example 1:
bool[] buttPos = { true, true, false, true };
GameVars.SetListBool(varLocal, "buttonPositions", buttPos);
// The array of bools will be save to a local game var as buttonPositions.

// Example 2:
cListInt myInts;
for (uint i = 0; i < 10; i++) myInts.Add(Math.RandomInt(1, 101));
GameVars.SetListInt("mySavedInts", myInts);
// Ten random integers will be saved to a global game var as mySavedInts.
</syntaxhighlight>

====SetListItem...()====
<syntaxhighlight lang="cpp">
void SetListItemInt(enumVarScope aScopeOption, string asName, uint aulIndex, int alValue)
void SetListItemFloat(enumVarScope aScopeOption, string asName, uint aulIndex, float afValue)
void SetListItemString(enumVarScope aScopeOption, string asName, uint aulIndex, string asValue)
void SetListItemBool(enumVarScope aScopeOption, string asName, uint aulIndex, bool abValue)
void SetListItemVector(enumVarScope aScopeOption, string asName, uint aulIndex, cVector avhValue)
void SetListItemRotator(enumVarScope aScopeOption, string asName, uint aulIndex, cRotator avhValue)
void SetListItemPoint(enumVarScope aScopeOption, string asName, uint aulIndex, cPoint avhValue)
</syntaxhighlight>
Sets the value of a single item in a stored game variable list, at the specified index. If the specified index is past the end of the list (or if the list has not been stored), then the list will be extended with default values.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list.
#''uint aulIndex'' - The index in the stored list to set the value.
#''int alValue, float afValue, string asValue, bool abValue, cVector avhValue, cRotator avhValue, or cPoint avhValue'' - A value of the appropriate type to be set as the item in the named game variable list.
<syntaxhighlight lang="cpp">
// Example 1:
bool[] buttPos = { true, true, false, true };
GameVars.SetListBool(varLocal, "buttonPositions", buttPos);
GameVars.SetListItemBool(varLocal, "buttonPositions", 2, true);
// All four saved bools in the local game var buttonPositions are now true.

// Example 2:
GameVars.SetListInt("newListOfInts", 10, 99);
// Assuming newListOfInts has not been created yet, a list of 9 default 0's is created, followed by 99.
</syntaxhighlight>

====AddListItem...()====
<syntaxhighlight lang="cpp">
void AddListItemInt(enumVarScope aScopeOption, string asName, int alValue)
void AddListItemFloat(enumVarScope aScopeOption, string asName, float afValue)
void AddListItemString(enumVarScope aScopeOption, string asName, string asValue)
void AddListItemBool(enumVarScope aScopeOption, string asName, bool abValue)
void AddListItemVector(enumVarScope aScopeOption, string asName, cVector avhValue)
void AddListItemRotator(enumVarScope aScopeOption, string asName, cRotator avhValue)
void AddListItemPoint(enumVarScope aScopeOption, string asName, cPoint avhValue)
</syntaxhighlight>
Appends a single item to the end of a stored game variable list.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list.
#''int alValue, float afValue, string asValue, bool abValue, cVector avhValue, cRotator avhValue, or cPoint avhValue'' - A value of the appropriate type to be appended to the named game variable list.
<syntaxhighlight lang="cpp">
// Example:
bool[] buttPos = { true, true, true, true };
GameVars.SetListBool(varLocal, "buttonPositions", buttPos);
GameVars.AddListItemBool(varLocal, "buttonPositions", false);
// The saved list of four true bools in the local game var buttonPositions is now append with a false value.
</syntaxhighlight>

====GetList...()====
<syntaxhighlight lang="cpp">
cListInt GetListInt(enumVarScope aScopeOption, string asName)
cListFloat GetListFloat(enumVarScope aScopeOption, string asName)
cListString GetListString(enumVarScope aScopeOption, string asName)
cListBool GetListBool(enumVarScope aScopeOption, string asName)
cListVector GetListVector(enumVarScope aScopeOption, string asName)
cListRotator GetListRotator(enumVarScope aScopeOption, string asName)
cListPoint GetListPoint(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Retrieves an entire stored game variable list and returns it as a linked list of the appropriate type.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list to retrieve.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myFloats = GetListFloat("savedFloats");
// The script var list myFloats is assigned with the values retrieved from the game var list savedFloats.

// Example 2:
float[] myFloats = GetListFloat("savedFloats").ToArray();
// The script var array myFloats is assigned with the values retrieved from the game var list savedFloats, using the ToArray() method of the list class.

// Example 3:
float myFloat = GetListFloat("savedFloats")[3];
// The script var float myFloat is assigned with the single value retrieved from index 3 of the game var list savedFloats.
</syntaxhighlight>

====GetListItem...()====
<syntaxhighlight lang="cpp">
cListInt GetListItemInt(enumVarScope aScopeOption, string asName, uint aulIndex)
cListFloat GetListItemFloat(enumVarScope aScopeOption, string asName, uint aulIndex)
cListString GetListItemString(enumVarScope aScopeOption, string asName, uint aulIndex)
cListBool GetListItemBool(enumVarScope aScopeOption, string asName, uint aulIndex)
cListVector GetListItemVector(enumVarScope aScopeOption, string asName, uint aulIndex)
cListRotator GetListItemRotator(enumVarScope aScopeOption, string asName, uint aulIndex)
cListPoint GetListItemPoint(enumVarScope aScopeOption, string asName, uint aulIndex)
</syntaxhighlight>
Retrieves a single item from a stored game variable list and returns it as variable of the appropriate type.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list to retrieve the item from.
#''uint aulIndex'' - The index to get from the stored list.
<syntaxhighlight lang="cpp">
// Example:
string[] sItems = { "bucket", "hammer", "saw", "pliers" };
GameVars.SetListString("itemNames", sItems);
string sRetirevedItem = GameVars.GetListItem("itemNames", 2);
// sRetirevedItem becomes "saw".
</syntaxhighlight>

====GetListCount()====
<syntaxhighlight lang="cpp">
uint GetListCount(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Returns the number of items stored in a list.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list.
<syntaxhighlight lang="cpp">
// Example:
SetNumberOfQuestsInMap(GameVars.GetListCount(varLocal, "activeQuests"));
// The number of items in the saved game var activeQuests is retrieved and passed to SetNumberOfQuestsInMap() as an arg.
</syntaxhighlight>

====ClearList()====
<syntaxhighlight lang="cpp">
void ClearList(enumVarScope aScopeOption, string asName)
</syntaxhighlight>
Empties a stored list.
 Note: This works by zeroing the count and does not remove or reset the items in the stored list. If GetList...() is used after ClearList() then it will return an empty list. But if GetListItem...() is used after ClearList(), it will still return the previously stored item.
 aScopeOption is optional. If varLocal is used, the game variable is saved for the current level only. If varGlobal is used or if aScopeOption is omitted, the game variables will be saved for all levels.
#''enumVarScope aScopeOption'' - Can be either varLocal or varGlobal. (Optional, default = varGlobal)
#''string asName'' - The name of the stored game variable list.
<syntaxhighlight lang="cpp">
// Example:
bool[] bBunchOfBools = { true, false, false, true };
GameVars.SetListBool(varLocal, "SavedBools", bBunchOfBools);
GameVars.ClearList("SavedBools);

int lTryGetCount = GameVars.GetListCount("SavedBools");
cListBool bTryGetList = GameVars.GetListBool("SavedBools");
bool bTryGetIndex = GameVars.GetListItemBool("SavedBools", 3);
// After clearing the list, lTryGetCount is assigned 0, and bTryGetList is assigned an empty list.
// However, bTryGetIndex will be assigned true, and the original value is not erased.
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Debug

2024-02-11T01:07:11Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Debug.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script file "HelperScripts_Debug.hps" provides more control and options for how debug messages are written to the screen and to the log. There are three purposes behind Debug.

===Verbosity===
The first is '''verbosity levels'''. Verbosity means "wordiness". Debug defines three verbosity values that control how much debug information is posted to screen and log files. The modder can control the verbosity level in script, and create lots of debug output whilst only spamming the screen and log when actually needed. The SetVerbosity() method, and the properties VerbosityInLogFile, VerbosityOnScreen and LogInReleaseMode, can be used to set a verbosity level 0-3 for posting messages to the screen in debug mode, to the log in debug mode and to the log in normal mode.
 When using Debug's Message() method to post debug messages, they are given a priority level, 1-3, which is checked against the verbosity level. Priority level 1 should be used for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages. For example:
<syntaxhighlight lang="cpp">
Debug.VerbosityInLogFile = 2;
Debug.VerbosityOnScreen = 1;
Debug.Message(1, "With the current settings, this will appear onscreen and in the log.");
Debug.Message(2, "With the current settings, this will appear in the log only.");
Debug.Message(3, "With the current settings, this won't appear anywhere.");
</syntaxhighlight>

===New Types and Formatting===
Secondly, Debug provides methods to pass multiple '''new argument types'''. As well as composing messages from strings, ints, etc., you can also pass arrays, lists, vectors, or make use of the String.Format() method and Str class.

===Performance===
And thirdly, Debug allow modders to include complex debug messages whilst '''computing strings in debug mode only'''. For example, sometimes it's useful to have complex debug messages incorporating lots of variables. Compare these two lines of script:
<syntaxhighlight lang="cpp">
// Example 1 - The basic way:
AddDebugMessage("A grunt has arrived, grunt number: " + gruntNum, true);
AddDebugMessage("Grunt number " + gruntNum + " has touched area " + triggerName + "!", true);
// Example 2 - The Helper Scripts way:
Debug.Message(3, "A grunt has arrived, grunt number", gruntNum);
Debug.Message(3, "Grunt number {0} has touched area {1}!", Str(gruntNum), Str(triggerName));
</syntaxhighlight>
Both examples give the same output, visually. In example 1, the work to compose the final string happens at the point of calling AddDebugMessage(), ''regardless of whether debug mode is active or not''. That's not a big deal if it's not used often, but processing a lot of complex debug messages can have a performance impact even while the player is playing the game outside of debug mode. In example 2, Debug provides methods to pass the parts of the string as individual arguments, and the string computation only takes place if the message will actually be posted to the screen or log file. This doesn't improve performance in debug mode, but if a lot of complex debug messages are used then it will improve performance in normal play mode.

=Debug=

==Behaviours==
"HelperScripts_Debug.hps" declares an object called '''Debug''', of the new script class cDebug. To access its properties and methods, just use "Debug." followed by the function call or property. E.g.:
<syntaxhighlight lang="cpp">
Debug.Message(1, "this is an error message!");
Debug.LogInReleaseMode = false;
</syntaxhighlight>

==Properties==
Debug provides the following properties:

====VerbosityInLogFile====
<syntaxhighlight lang="cpp">
uint VerbosityInLogFile
</syntaxhighlight>
The integer property VerbosityInLogFile can get or set the minimum priority for Debug messages printed to the log file. (See also: SetVerbosity())
<syntaxhighlight lang="cpp">
// Example:
Debug.VerbosityInLogFile = 3;
</syntaxhighlight>

====VerbosityOnScreen====
<syntaxhighlight lang="cpp">
uint VerbosityOnScreen
</syntaxhighlight>
The integer property VerbosityOnScreen can get or set the minimum priority for Debug messages shown on-screen. (See also: SetVerbosity())
<syntaxhighlight lang="cpp">
// Example:
Debug.VerbosityOnScreen = 1;
</syntaxhighlight>

====LogInReleaseMode====
<syntaxhighlight lang="cpp">
bool LogInReleaseMode
</syntaxhighlight>
The bool property LogInReleaseMode can get or set whether to print debug messages to the log file even when debug mode is off. If set to true, the same priority as VerbosityInLogFile is used. (See also: SetVerbosity())
<syntaxhighlight lang="cpp">
// Example:
Debug.LogInReleaseMode = true;
</syntaxhighlight>

====CheckForDuplicates====
<syntaxhighlight lang="cpp">
bool CheckForDuplicates
</syntaxhighlight>
The bool property CheckForDuplicates can get or set whether on-screen messages are checked for duplicates. This is the same as the abCheckForDuplicates argument in the global function AddDebugMessage(). The default is false because, using Debug, the modder can use verbosity levels to control spamming instead.
<syntaxhighlight lang="cpp">
// Example:
Debug.CheckForDuplicates = true;
</syntaxhighlight>

==Methods==
Debug provides the following methods:

====SetVerbosity()====
<syntaxhighlight lang="cpp">
void SetVerbosity(uint aulOnScreen, uint aulLogAlways, uint aulLogDebug)
</syntaxhighlight>
Changes the verbosity limits at runtime. They are not saved, so they will reset to default on level load. (See also: VerbosityInLogFile, VerbosityOnScreen and LogInReleaseMode properties)
#''uint aulOnScreen'' - The new minimum priority for Debug messages shown on-screen.
#''uint aulLogAlways'' - The new minimum priority for Debug messages printed to the log file when debug mode is off.
#''uint aulLogDebug'' - The new minimum priority for Debug messages printed to the log file when debug mode is on.
<syntaxhighlight lang="cpp">
// Example:
Debug.SetVerbosity(0, 1, 3);
</syntaxhighlight>

====TestPriority()====
<syntaxhighlight lang="cpp">
bool TestPriority(uint aulPrio)
</syntaxhighlight>
Returns true if a message of the given priority would be posted at all.
#''uint aulPrio'' - The priority level to be tested.
<syntaxhighlight lang="cpp">
// Example:
if (Debug.TestPriority(3))
{
// Do some fancy debug stuff.
}
</syntaxhighlight>

===Message()===
 Message() can be used to post a debug message to the log and/or screen. It is intended as a replacement for AddDebugMessage() and Print().
 There are multiple overloads of Message() that allow for different types of arguments. In each case the string computation only happens if the message will actually be posted.
 alPrio represents the importance of your message, 1-3. alPrio is checked against the relevant verbosity limit. In general, use priority level 1 for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages.

====Basic message====
<syntaxhighlight lang="cpp">
void Message(const alPrio, string asText)
</syntaxhighlight>
Posts a debug message to the log and/or screen. alPrio is optional and defaults to 1 if omitted.
#''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
#''string asText'' - The text of the message.
<syntaxhighlight lang="cpp">
// Example:
Debug.Message(3, "Something has happened."); // Priority 3.
Debug.Message("Something else has happened."); // Priority 1.
</syntaxhighlight>

====Message appended with a variable====
<syntaxhighlight lang="cpp">
void Message(uint alPrio, string asText, string arg)
void Message(uint alPrio, string asText, uint arg)
void Message(uint alPrio, string asText, int arg)
void Message(uint alPrio, string asText, float arg)
void Message(uint alPrio, string asText, double arg)
void Message(uint alPrio, string asText, bool arg)
void Message(uint alPrio, string asText, cVector arg)
void Message(uint alPrio, string asText, cPoint arg)
void Message(uint alPrio, string asText, cRotator arg)
void Message(uint alPrio, string asText, cBezier arg)
void Message(uint alPrio, string asText, cSpline arg)
</syntaxhighlight>
Appends a single variable to the debug message, evaluating the arguments only if the message will be posted. alPrio is optional and defaults to 1 if omitted.
#''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
#''string asText'' - The text of the message, to be appended to.
#''string arg, uint arg, int arg, float arg, double arg, bool arg, cVector arg, cPoint arg, cBezier arg, or cSpline arg'' - A variable to be appended to the message.
<syntaxhighlight lang="cpp">
// Example:
bool bSpookyZone = true;
Debug.Message(2, "Player is in spooky zone", bSpookyZone);
// outputs "Player is in spooky zone: true" at verbosity level 2
</syntaxhighlight>

====Message appended with a list====
<syntaxhighlight lang="cpp">
void Message(uint alPrio, string asText, cListBase ahList)
</syntaxhighlight>
Appends a [[HPL2/HPL2_Helper_Scripts/Lists|list]] object to the message. The list is only evaluated if the message will actually be posted. Any derived list class can be used, including cListInt, cListFloat, cListBool, etc.. Uses the ToStringArray() function of the list, which is turn uses the ToString() function of the relevant node class. alPrio is optional and defaults to 1 if omitted.
#''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
#''string asText'' - The text of the message.
#''cListBase ahList'' - A reference to a list class that will be appended to the message.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myFloats;
myFloats.Add(11.1f);
myFloats.Add(2.22f);
Debug.Message(3, "Let's print some floats", myFloats);
// outputs "Let's print some floats: [11.1], [2.22]" at verbosity level 3
</syntaxhighlight>

====Message appended with an array====
<syntaxhighlight lang="cpp">
void Message(uint alPrio, string asText, int[] alArray)
void Message(uint alPrio, string asText, float[] afArray)
void Message(uint alPrio, string asText, double[] adArray)
void Message(uint alPrio, string asText, bool[] abArray)
void Message(uint alPrio, string asText, string[] asArray)
</syntaxhighlight>
Appends an array of values to the message. The array is only evaluated if the message will actually be posted. alPrio is optional and defaults to 1 if omitted.
#''alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
#''asText'' - The text of the message.
#''int[] alArray, float[] afArray, double[] adArray, bool[] abArray, or string[] asArray'' - A reference to a list that will be appended to the message.
<syntaxhighlight lang="cpp">
// Example:
string[] someWords = { "good", "boy", "Daniel" };
Debug.Message(1, "You're a", someWords);
// outputs "You're a: [good], [boy], [Daniel]" at verbosity level 1
</syntaxhighlight>

====Message with string formatting====
<syntaxhighlight lang="cpp">
void Message(const alPrio, Str@[] argArray)
void Message(uint alPrio, Str arg0, Str arg1, ... Str arg7);
</syntaxhighlight>
The most versatile overload of Message(). The debug message is a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero.
 This uses the String.Format() method, allowing an arbitrary number of variables to be inserted into a string, using the Str class, regardless of data type. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable.
 When using the array version, the Str arguments can be provided as Str@[] - an array of ''handles''. Be sure to declare an array of Str handles (Str@[]) rather than an array of Str instances (Str[]). See Example 3. ('''Advanced users''' may note that Angelscript handles work similarly reference parameters, or pointers in C++.)
#''alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
#''asText'' - The text of the message as a template containing tokens ("{i}") to be replaced by the other arguments.
#''Str@[] argArray, or Str arg0'' - An array of Str handles, or a single Str instance, to replace tokens in the string.
#''Str arg1 ... Str arg7'' - An additional 7 single Str arguments can be given. '''(Optional, when not using an array.)'''
<syntaxhighlight lang="cpp">
// Example 1:
string sPlayerName = "Justine";
string sSuitorName = "Basile";
int lScore = 7;
int lScoreMax = 10;
Debug.Message(1, "{0} has been given {1}/{2} by {3}!", Str(sSuitorName), Str(lScore), Str(lScoreMax), Str(sPlayerName));
// Outputs "Basile has been given 7/10 by Justine!"

// Example 2:
int lNumMonsters = 13;
string sMonsterType = "ManPig";
Debug.Message(1, "Error: Too many {3}s! {0} out of {1} found. Pork = {2}!", Str(lNumMonsters), Str(12), Str(lNumMonsters > 12), Str(sMonsterType));
// Outputs "Error: Too many ManPigs! 13 out of 12 found. Pork = true!"
// Note that the numbers match the order of the args, not the order of insertion.

// Example 3:
Str@[] someArgs(2);
someArgs[0] = Str("strange");
someArgs[1] = Str("unnartural");
Debug.Message(3, "The darkness in the Storage feels {0} and {1}.", someArgs);
// Outputs "The darkness in the Storage feels strange and unnatural."
// Note the syntax for declaring the array: "Str@[]"
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts

2024-02-03T12:08:19Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

The current version is [[HPL2/HPL2_Helper_Scripts#Version_1.1.2C_03.2F02.2F24|1.1]].

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetSegmentHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusic(), StopMusic(), IsMusicPlaying(), DuckStart(), DuckRestore()
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2024-02-03T12:05:25Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

The current version is [[HPL2/HPL2_Helper_Scripts#Version_1.1.2C_03.2F02.2F24|1.1]].

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetSegmentHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusic(), StopMusic(), DuckStart(), DuckRestore()
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2024-02-03T11:53:08Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

The current version is [[HPL2/HPL2_Helper_Scripts#Version_1.1.2C_03.2F02.2F24|1.1]].

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetBezierHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusic(), StopMusic(), DuckStart(), DuckRestore()
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2024-02-03T11:51:24Z

Mrbehemo: Added change log section, inc 1.1

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

=Change Log=
It should be simple to upgrade existing projects to use the current version, but take note of the changes listed below. You may need to make some minor edits.

==Version 1.1, 03/02/24==
* General
** Changed some more spammy debug messages in level 2 to level 3 in various classes.
** Fixed various sign mismatch warnings between ints and uints.

* Debug
** Default log verbosity is now 2 instead of 3.

* GameVars
** Added SetIntAsUint() method, which is just SetInt() with an explicit cast.

* Lists
** New properties for all list types: DefaultValue, Capacity
** New methods for all list types: Fill(), Extend(), AddUnique(), ToString()
** Fixed silent exception that occured when Insert() was used with index 0.
** Fixed silent exception that occured when Pop() was used with a count of 0 or 1.
** Fixed behaviour of Find() and RemoveItem() in cListGeneric.
** Added '''==''' operator to cListBase for checking if two lists of the same type are equal.
** Added optional argument abExtend to Set() methods.
** Fixed issue with incorrectly overloading Pop(), by moving the generic Pop() from cListBase to its correct place in cListGeneric.

* Math
** New method in cMath: DistToEntity()
** RandomVector3d() and RandomVector2d(), when using the vecNormal option or when no range is specified, now have a chance of returning a vector with negative axes, whereas previously they were always positive.

* String
** New method in cString: NearlyEqual()
** SplitToList() and SplitToArray() now handle empty strings by returning an empty collection. (As to opposed to previously returning a collection of one empty string.)
** Added list behaviour to Str class.

* Vectors
** New methods in cVector: DotProduct(), CrossProduct()
** New methods in cSpline: GetBezierHandle(), GetMinLength()
** Both cVector and cPoint now implement '''* / *= /=''' operators as ''per component'' multipliers, e.g. [2, 2, 2] * [1, 3, 0.5] = [2, 6, 1]
** If cVector * cVector was previously used where a dot product was the intended result, that should now be replaced by the DotProduct() method.
** Tweaked the bezier behaviour that uses a single control point to better approximate a quadratic bezier.

* Fader
** New methods in cFader: PlayMusic(), StopMusic(), DuckStart(), DuckRestore()
** Group 0 now counts as "no group".
** Added "Null" behaviour - Fader sounds initialised with a name containing "Null" will not be associated with a sound entity in the map, but they can be included in a group and have a play state as normal.
** Fader sounds can now be marked as StopOnMusic. If Fader.PlayMusic() and Fader.StopMusic() are used, then Fader sounds with StopOnMusic will fade out when music starts.

* Glitcher
** Fixed the afChanceScale multiplier when adding glitches. (Was previously inverted).
** Slightly reduced the default max glitch frequency, for smoother fades.

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2024-01-06T12:02:20Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.

There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem)
bool Set(uint aulIndex, float afItem)
bool Set(uint aulIndex, double adItem)
bool Set(uint aulIndex, bool abItem)
bool Set(uint aulIndex, string asItem)
bool Set(uint aulIndex, cVector avItem)
bool Set(uint aulIndex, cPoint avItem)
bool Set(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Assigns a new value to an indexed item in the list, if it exists. If the list is shorter than the index or the item cannot be added, this returns false. If it was successfull set, it returns true.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
<syntaxhighlight lang="cpp">
// Example:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Converting lists===
cListBase and its derived classes provide the following methods for converting lists into other types of collections:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToStringArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns a new string representing the whole list, by getting string versions of each item in the list and joining them. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2024-01-06T12:00:13Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.

There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem)
bool Set(uint aulIndex, float afItem)
bool Set(uint aulIndex, double adItem)
bool Set(uint aulIndex, bool abItem)
bool Set(uint aulIndex, string asItem)
bool Set(uint aulIndex, cVector avItem)
bool Set(uint aulIndex, cPoint avItem)
bool Set(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Assigns a new value to an indexed item in the list, if it exists. If the list is shorter than the index or the item cannot be added, this returns false. If it was successfull set, it returns true.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
<syntaxhighlight lang="cpp">
// Example:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Converting lists===
cListBase and its derived classes provide the following methods for converting lists into other types of collections:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToStringArray()
</syntaxhighlight>
Makes a new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Makes a new string representing the whole list, by joining string versions of each item in the list, and returns the string. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

Hpl2:HPL2/Tutorials/CustomSounds

2024-01-05T17:33:01Z

Mrbehemo:

= Adding custom sounds =
== Preparing the sounds ==

First you'll need a sound-editting program; [https://www.audacityteam.org/ Audacity] is a common choice - it is free and will suit most needs.

The sounds need to be in '''.ogg ''' format. If your sound files are formatted as '''.MP3''', '''.WAV''' or anything else, you need to use one your audio editing software of choice to convert your sound file to an '''.ogg''' file format. In Audacity, you just need to drag the file into the program and then export as '''.ogg'''.

{{tip|It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.}}

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

== Managing sound files ==

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but '''sounds''' would probably be the best.

{{tip|If your mod has a lot of custom sounds, make sure to organise them into subfolders!}}

Place the tutorial.ogg file in the created (sub)folder.

== Creating the sound entity file ==

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a '''.snt''' extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

{{tip|If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.}}

Alternatively, you can do the following:

Create a '''.txt''' file and name it what you want (same as the .ogg file is common), open it with any text editor you use.[[Notepad%2B%2B | Notepad++]] is recommended. When you finish editing the file, change the extension to the correct one. I named my file '''tutorial.snt'''.

{{tip|Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.}}

In the file, you can edit quite a few things, and among them is..''Adding your sound-file into the script!'' And since my sound file is '''door''''''.ogg''', It shall go to the '''MAIN''' section. Random soundfiles will be covered later on.
<syntaxhighlight lang="xml">
<SOUNDENTITY>
<SOUNDS>
<Main>
<Sound File="door.ogg" />
</Main>
</SOUNDS>
<PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>
</syntaxhighlight>

Format explanation:

<'''SOUNDENTITY'''> is the start marker of the sound file

<'''SOUNDS'''> indicates the sound list

<'''Main'''> is the list of sounds the file will play.

<'''Sound File'''="''YourFileName''.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<'''PROPERTIES'''> Are all the options you may use to decide how the sound will behave in-game.

==Properties==

===The basics===

* '''Volume''' is how loud the sound should play. '''Volume=1''' would make the sound play at the normal volume of the sound file. '''Volume=0.5''' would half as loud. '''Volume=2''' would amplify the sound to twice its normal volume.

* '''MinDistance''' and '''MaxDistance''' are used for attenuation, which means how the sound fades out over distance. Within the '''MinDistance''' the sound will be at the full '''Volume''' level. As the player moves from '''MinDistance''' to '''MaxDistance''' away from the sound, the volume will fade towards silence. Outside of '''MaxDistance''' it does not play at all.

* '''Loop''' should be set to '''"true"''' if the sound should loop.

* '''Use3D''' should be set to '''"true"''' if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with <code>PlaySoundAtEntity();</code> in your level script (check [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] for details).

===More advanced .snt properties===

* '''Loop''', '''Random''' and '''Interval''' are all used together to define whether and how the sound should loop. '''Loop=true''' will make the sound repeat. If '''Interval''' is 0 then the sound will loop continuously, but if '''Interval''' is set to a value > 0, then that becomes a delay inserted between the repeitions. If '''Random''' is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If '''Random''' is <=0 or >=1, then the sound will always play every interval.
For example, an ambient background track that should play continuously with no gaps should have:
<syntaxhighlight lang="xml">Random="1" Interval="0" Loop="true"</syntaxhighlight>
A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:
<syntaxhighlight lang="xml">Random="0.25" Interval="15" Loop="true"</syntaxhighlight>

* '''Random''' does ''not'' affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

* '''Use3D''' causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If '''Use3D''' is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as '''Use3d="false"'''.

* '''Stream''' defines whether the sound can be preloaded. '''Stream="false"''' is the normal behaviour for short sounds that are loaded into memory and played when needed. '''Stream="true"''' makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

* '''FadeEnd''' and '''FadeStart''', if true, will cause looping sounds to fade in or out on their first or last repetition.

* '''Blockable''', '''BlockVolumeMul''', and '''Priority''' do not seem to be implemented in the engine. ''('''Blockable''' and '''BlockVolumeMul''' may have been intended to define how the sounds are muffled by world geometry, and '''Priority''' may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.)'' {{confirm}}

* '''<SOUNDS>''' categories: as well as '''<Main>''' the engine will also read lists of sounds from '''<Start>''' and '''<Stop>''' nodes. These may provide alternate sounds for the beginning and end of a loop. {{confirm}}

=Adding custom music==

Custom music only needs to be a file in the '''.ogg''' format. It won't need an '''.snt''' file to be played with <code>PlayMusic();</code> or at the credits, but you won't be able to use <code>PlaySoundAtEntity();</code> with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. '''music'''. Put the '''.ogg''' file there.

See [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] to learn how to use <code>PlayMusic();</code>.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.

Hpl2:HPL2/Tutorials/CustomSounds

2024-01-05T12:17:51Z

Mrbehemo:

= Adding custom sounds =
== Preparing the sounds ==

First you'll need a sound-editting program; [https://www.audacityteam.org/ Audacity] is a common choice - it is free and will suit most needs.

The sounds need to be in '''.ogg ''' format. If your sound files are formatted as '''.MP3''', '''.WAV''' or anything else, you need to use one your audio editing software of choice to convert your sound file to an '''.ogg''' file format. In Audacity, you just need to drag the file into the program and then export as '''.ogg'''.

{{tip|It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.}}

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

== Managing sound files ==

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but '''sounds''' would probably be the best.

{{tip|If your mod has a lot of custom sounds, make sure to organise them into subfolders!}}

Place the tutorial.ogg file in the created (sub)folder.

== Creating the sound entity file ==

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a '''.snt''' extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

{{tip|If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.}}

Alternatively, you can do the following:

Create a '''.txt''' file and name it what you want (same as the .ogg file is common), open it with any text editor you use.[[Notepad%2B%2B | Notepad++]] is recommended. When you finish editing the file, change the extension to the correct one. I named my file '''tutorial.snt'''.

{{tip|Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.}}

In the file, you can edit quite a few things, and among them is..''Adding your sound-file into the script!'' And since my sound file is '''door''''''.ogg''', It shall go to the '''MAIN''' section. Random soundfiles will be covered later on.
<syntaxhighlight lang="xml">
<SOUNDENTITY>
<SOUNDS>
<Main>
<Sound File="door.ogg" />
</Main>
</SOUNDS>
<PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>
</syntaxhighlight>

Format explanation:

<'''SOUNDENTITY'''> is the start marker of the sound file

<'''SOUNDS'''> indicates the sound list

<'''Main'''> is the list of sounds the file will play.

<'''Sound File'''="''YourFileName''.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<'''PROPERTIES'''> Are all the options you may use to decide how the sound will behave in-game.

==Properties==

===The basics===

* '''Volume''' is how loud the sound should play. '''Volume=1''' would make the sound play at the normal volume of the sound file. '''Volume=0.5''' would half as loud. '''Volume=2''' would amplify the sound to twice its normal volume.

* '''MinDistance''' and '''MaxDistance''' are used for attenuation, which means how the sound fades out over distance. Within the '''MinDistance''' the sound will be at the full '''Volume''' level. As the player moves from '''MinDistance''' to '''MaxDistance''' away from the sound, the volume will fade towards silence. Outside of '''MaxDistance''' it does not play at all.

* '''Loop''' should be set to '''"true"''' if the sound should loop.

* '''Use3D''' should be set to '''"true"''' if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with <code>PlaySoundAtEntity();</code> in your level script (check [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] for details).

===More advanced .snt properties===

* '''Loop''', '''Random''' and '''Interval''' are all used together to define whether and how the sound should loop. '''Loop=true''' will make the sound repeat. If '''Interval''' is 0 then the sound will loop continuously, but if '''Interval''' is set to a value > 0, then that becomes a delay inserted between the repeitions. If '''Random''' is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If '''Random''' is <=0 or >=1, then the sound will always play every interval.
For example, an ambient background track that should play continuously with no gaps should have:
<syntaxhighlight lang="xml">Random="1" Interval="0" Loop="true"</syntaxhighlight>
A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:
<syntaxhighlight lang="xml">Random="0.25" Interval="15" Loop="true"</syntaxhighlight>

* '''Random''' does ''not'' affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

* '''Use3D''' causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If '''Use3D''' is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as '''Use3d="false"'''.

* '''Stream''' defines whether the sound can be preloaded. '''Stream="false"''' is the normal behaviour for short sounds that are loaded into memory and played when needed. '''Stream="true"''' makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

* '''FadeEnd''' and '''FadeStart''', if true, will cause looping sounds to fade in or out on their first or last repetition.

* '''Blockable''' and '''BlockVolumeMul''' were probably intended to define how the sound can interact with world geometry, but they do not seem to be implemented in the engine.

* '''Blockable''', '''BlockVolumeMul''', and '''Priority''' do not seem to be implemented in the engine. ''('''Blockable''' and '''BlockVolumeMul''' may have been intended to define how the sounds are muffled by world geometry, and '''Priority''' may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.)'' {{confirm}}

* '''<SOUNDS>''' categories: as well as '''<Main>''' the engine will also read lists of sounds from '''<Start>''' and '''<Stop>''' nodes. These may provide alternate sounds for the beginning and end of a loop. {{confirm}}

=Adding custom music==

Custom music only needs to be a file in the '''.ogg''' format. It won't need an '''.snt''' file to be played with <code>PlayMusic();</code> or at the credits, but you won't be able to use <code>PlaySoundAtEntity();</code> with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. '''music'''. Put the '''.ogg''' file there.

See [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] to learn how to use <code>PlayMusic();</code>.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.

Hpl2:HPL2/Tutorials/CustomSounds

2024-01-05T12:14:43Z

Mrbehemo: Mrbehemo moved page Hpl2:Tutorials:script:CustomSounds to Hpl2:HPL2/Tutorials/CustomSounds: Correct path format

= Adding custom sounds =
== Preparing the sounds ==

First you'll need a sound-editting program; [https://www.audacityteam.org/ Audacity] is a common choice - it is free and will suit most needs.

The sounds need to be in '''.ogg ''' format. If your sound files are formatted as '''.MP3''', '''.WAV''' or anything else, you need to use one your audio editing software of choice to convert your sound file to an '''.ogg''' file format. In Audacity, you just need to drag the file into the program and then export as '''.ogg'''.

{{tip|It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.}}

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

== Managing sound files ==

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but '''sounds''' would probably be the best.

{{tip|If your mod has a lot of custom sounds, make sure to organise them into subfolders!}}

Place the tutorial.ogg file in the created (sub)folder.

== Creating the sound entity file ==

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a '''.snt''' extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

{{tip|If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.}}

Alternatively, you can do the following:

Create a '''.txt''' file and name it what you want (same as the .ogg file is common), open it with any text editor you use.[[Notepad%2B%2B | Notepad++]] is recommended. When you finish editing the file, change the extension to the correct one. I named my file '''tutorial.snt'''.

{{tip|Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.}}

In the file, you can edit quite a few things, and among them is..''Adding your sound-file into the script!'' And since my sound file is '''door''''''.ogg''', It shall go to the '''MAIN''' section. Random soundfiles will be covered later on.
<syntaxhighlight lang="xml">
<SOUNDENTITY>
<SOUNDS>
<Main>
<Sound File="door.ogg" />
</Main>
</SOUNDS>
<PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>
</syntaxhighlight>

Format explanation:

<'''SOUNDENTITY'''> is the start marker of the sound file

<'''SOUNDS'''> indicates the sound list

<'''Main'''> is the list of sounds the file will play.

<'''Sound File'''="''YourFileName''.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<'''PROPERTIES'''> Are all the options you may use to decide how the sound will behave in-game.

==Properties==

===The basics===

* '''Volume''' is how loud the sound should play. '''Volume=1''' would make the sound play at the normal volume of the sound file. '''Volume=0.5''' would half as loud. '''Volume=2''' would amplify the sound to twice its normal volume.

* '''MinDistance''' and '''MaxDistance''' are used for attenuation, which means how the sound fades out over distance. Within the '''MinDistance''' the sound will be at the full '''Volume''' level. As the player moves from '''MinDistance''' to '''MaxDistance''' away from the sound, the volume will fade towards silence. Outside of '''MaxDistance''' it does not play at all.

* '''Loop''' should be set to '''"true"''' if the sound should loop.

* '''Use3D''' should be set to '''"true"''' if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with <code>PlaySoundAtEntity();</code> in your level script (check [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] for details).

===More advanced .snt properties===

* '''Loop''', '''Random''' and '''Interval''' are all used together to define whether and how the sound should loop. '''Loop=true''' will make the sound repeat. If '''Interval''' is 0 then the sound will loop continuously, but if '''Interval''' is set to a value > 0, then that becomes a delay inserted between the repeitions. If '''Random''' is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If '''Random''' is <=0 or >=1, then the sound will always play every interval.
For example, an ambient background track that should play continuously with no gaps should have:
<syntaxhighlight lang="xml">Random="1" Interval="0" Loop="true"</syntaxhighlight>
A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:
<syntaxhighlight lang="xml">Random="0.25" Interval="15" Loop="true"</syntaxhighlight>

* '''Random''' does 'not' affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

* '''Use3D''' causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If '''Use3D''' is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as '''Use3d="false"'''.

* '''Stream''' defines whether the sound can be preloaded. '''Stream="false"''' is the normal behaviour for short sounds that are loaded into memory and played when needed. '''Stream="true"''' makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

* '''FadeEnd''' and '''FadeStart''', if true, will cause looping sounds to fade in or out on their first or last repetition.

* '''Blockable''' and '''BlockVolumeMul''' were probably intended to define how the sound can interact with world geometry, but they do not seem to be implemented in the engine.

* '''Blockable''', '''BlockVolumeMul''', and '''Priority''' do not seem to be implemented in the engine. ''('''Blockable''' and '''BlockVolumeMul''' may have been intended to define how the sounds are muffled by world geometry, and '''Priority''' may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.)'' {{confirm}}

* '''<SOUNDS>''' categories: as well as '''<Main>''' the engine will also read lists of sounds from '''<Start>''' and '''<Stop>''' nodes. These may provide alternate sounds for the beginning and end of a loop. {{confirm}}

=Adding custom music==

Custom music only needs to be a file in the '''.ogg''' format. It won't need an '''.snt''' file to be played with <code>PlayMusic();</code> or at the credits, but you won't be able to use <code>PlaySoundAtEntity();</code> with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. '''music'''. Put the '''.ogg''' file there.

See [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] to learn how to use <code>PlayMusic();</code>.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.

Hpl2:Tutorials:script:CustomSounds

2024-01-05T12:14:43Z

Mrbehemo: Mrbehemo moved page Hpl2:Tutorials:script:CustomSounds to Hpl2:HPL2/Tutorials/CustomSounds: Correct path format

#REDIRECT [[Hpl2:HPL2/Tutorials/CustomSounds]]

Hpl2:HPL2/Tutorials/CustomSounds

2024-01-05T12:13:04Z

Mrbehemo: Improved .snt properties descriptions. Created a "basics" and "advanced" section.

= Adding custom sounds =
== Preparing the sounds ==

First you'll need a sound-editting program; [https://www.audacityteam.org/ Audacity] is a common choice - it is free and will suit most needs.

The sounds need to be in '''.ogg ''' format. If your sound files are formatted as '''.MP3''', '''.WAV''' or anything else, you need to use one your audio editing software of choice to convert your sound file to an '''.ogg''' file format. In Audacity, you just need to drag the file into the program and then export as '''.ogg'''.

{{tip|It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.}}

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

== Managing sound files ==

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but '''sounds''' would probably be the best.

{{tip|If your mod has a lot of custom sounds, make sure to organise them into subfolders!}}

Place the tutorial.ogg file in the created (sub)folder.

== Creating the sound entity file ==

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a '''.snt''' extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

{{tip|If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.}}

Alternatively, you can do the following:

Create a '''.txt''' file and name it what you want (same as the .ogg file is common), open it with any text editor you use.[[Notepad%2B%2B | Notepad++]] is recommended. When you finish editing the file, change the extension to the correct one. I named my file '''tutorial.snt'''.

{{tip|Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.}}

In the file, you can edit quite a few things, and among them is..''Adding your sound-file into the script!'' And since my sound file is '''door''''''.ogg''', It shall go to the '''MAIN''' section. Random soundfiles will be covered later on.
<syntaxhighlight lang="xml">
<SOUNDENTITY>
<SOUNDS>
<Main>
<Sound File="door.ogg" />
</Main>
</SOUNDS>
<PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>
</syntaxhighlight>

Format explanation:

<'''SOUNDENTITY'''> is the start marker of the sound file

<'''SOUNDS'''> indicates the sound list

<'''Main'''> is the list of sounds the file will play.

<'''Sound File'''="''YourFileName''.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<'''PROPERTIES'''> Are all the options you may use to decide how the sound will behave in-game.

==Properties==

===The basics===

* '''Volume''' is how loud the sound should play. '''Volume=1''' would make the sound play at the normal volume of the sound file. '''Volume=0.5''' would half as loud. '''Volume=2''' would amplify the sound to twice its normal volume.

* '''MinDistance''' and '''MaxDistance''' are used for attenuation, which means how the sound fades out over distance. Within the '''MinDistance''' the sound will be at the full '''Volume''' level. As the player moves from '''MinDistance''' to '''MaxDistance''' away from the sound, the volume will fade towards silence. Outside of '''MaxDistance''' it does not play at all.

* '''Loop''' should be set to '''"true"''' if the sound should loop.

* '''Use3D''' should be set to '''"true"''' if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with <code>PlaySoundAtEntity();</code> in your level script (check [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] for details).

===More advanced .snt properties===

* '''Loop''', '''Random''' and '''Interval''' are all used together to define whether and how the sound should loop. '''Loop=true''' will make the sound repeat. If '''Interval''' is 0 then the sound will loop continuously, but if '''Interval''' is set to a value > 0, then that becomes a delay inserted between the repeitions. If '''Random''' is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If '''Random''' is <=0 or >=1, then the sound will always play every interval.
For example, an ambient background track that should play continuously with no gaps should have:
<syntaxhighlight lang="xml">Random="1" Interval="0" Loop="true"</syntaxhighlight>
A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:
<syntaxhighlight lang="xml">Random="0.25" Interval="15" Loop="true"</syntaxhighlight>

* '''Random''' does 'not' affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

* '''Use3D''' causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If '''Use3D''' is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as '''Use3d="false"'''.

* '''Stream''' defines whether the sound can be preloaded. '''Stream="false"''' is the normal behaviour for short sounds that are loaded into memory and played when needed. '''Stream="true"''' makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

* '''FadeEnd''' and '''FadeStart''', if true, will cause looping sounds to fade in or out on their first or last repetition.

* '''Blockable''' and '''BlockVolumeMul''' were probably intended to define how the sound can interact with world geometry, but they do not seem to be implemented in the engine.

* '''Blockable''', '''BlockVolumeMul''', and '''Priority''' do not seem to be implemented in the engine. ''('''Blockable''' and '''BlockVolumeMul''' may have been intended to define how the sounds are muffled by world geometry, and '''Priority''' may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.)'' {{confirm}}

* '''<SOUNDS>''' categories: as well as '''<Main>''' the engine will also read lists of sounds from '''<Start>''' and '''<Stop>''' nodes. These may provide alternate sounds for the beginning and end of a loop. {{confirm}}

=Adding custom music==

Custom music only needs to be a file in the '''.ogg''' format. It won't need an '''.snt''' file to be played with <code>PlayMusic();</code> or at the credits, but you won't be able to use <code>PlaySoundAtEntity();</code> with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. '''music'''. Put the '''.ogg''' file there.

See [http://wiki.frictionalgames.com/hpl2/amnesia/script_functions Engine scripts] to learn how to use <code>PlayMusic();</code>.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.

Hpl2:HPL2/Tutorials/CustomSounds

2024-01-05T11:12:16Z

Mrbehemo: Changed details of "Random" property.

HPL2/Tutorials/ShowScreenImage()

2024-01-04T17:27:42Z

Mrbehemo:

=Introduction=
ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

=Function=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
# ''afX'' - The X position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afY'' - The Y position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afScale'' - The size of the image in pixels, or original image size if negative (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
# ''afFadeIn'' - The time, in seconds, to fade in the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
# ''afFadeOut'' - The time, in seconds, to fade out the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])

=Size=
* Note that the ''afScale'' argument is ''not'' actually the scale of the image: it is the ''size in pixels''. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively.
* If the size is specified, the image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.
* If the size is given as -1 (or any number less than 0) then the actual pixel size and shape of the image file.

=Placement=
* The origin of the screen-space is the centre. This means that [0, 0] is the centre of the screen regardless of screen resolution, and regardless of ''abUseRelativeCoordinates''.
* The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go.
* If ''abUseRelativeCoordinates'' is ''false'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as actual pixels''.
* If ''abUseRelativeCoordinates'' is ''true'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as a fraction of the screen resolution width or height''.
* The relative co-ordinates still use the centre of the screen as the origin, so the top-left corner of the screen is [-0.5, -0.5] and the bottom-right corner is [0.5, 0.5]. Any relative co-ordinate greater than 0.5 will put the image outside of the screen.

=Timing=
* The total time that the image will be displayed is ''afFadeIn'' + ''afDuration'' + ''afFadeOut''.
* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
* Calling ShowScreenImage() again will replace the current image, regardless of duration or fade times.

=Examples=
<syntaxhighlight lang="c++">
// Centred:
ShowScreenImage("image.dds", -150.0f, -150.0f, 300.0f, false, 3.0f, 0.0f, 0.0f);
// Size: 300 x 300 pixels
// Placement: centred on the screen (image-origin is placed image-size/2 from the screen-origin)
// Timing: 3 seconds, no fading

// From top-left:
ShowScreenImage("image.dds", -0.45f, -0.45f, -1.0f, true, 2.0f, 1.0f, 2.0f);
// Size: original pixel size and shape of the image file
// Placement: near the top-left corner, with a 5% margin relative to the screen size
// Timing: 5 seconds, including fading

// From top-centre:
ShowScreenImage("image.dds", -0.48f, 0.0f, 100.0f, true, 0.0f, 2.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-centre, with a 2% margin relative to the screen size
// Timing: 4 seconds, fading out immediately after fading in

// Bottom-right - not reliable
ShowScreenImage("image.dds", 0.25f, 0.25f, 270.0f, true, 1.0f, 1.0f, 1.0f);
// With a screen resolution of 1920 x 1080, this would fit neatly into the bottom-right 1/16 of the screen (1080 / 4 = 270).
// Unfortunately, if the resolution was lower, it would not fit on the screen. And if the resolution was higher, it would not reach the edges.

// Full-screen kinda... top-left focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom-right with lower resolutions.
// At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

// Full-screen kinda... centre focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would stay on the centre of the screen, whatever the resolution.
// At lower resolutions all the edges would be cropped. At higher resolutions it would not fill the screen.
</syntaxhighlight>

=Conclusion=
There are lots of things you can do with ShowScreenImage() if you use it creatively!

...But if you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

HPL2/Tutorials/ShowScreenImage()

2024-01-04T17:26:53Z

Mrbehemo:

=Introduction=
ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

=Function=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
# ''afX'' - The X position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afY'' - The Y position of the image, relative to the centre of the screen (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afScale'' - The size of the image in pixels, or original image size if negative (see [[HPL2/Tutorials/ShowScreenImage()#Size|Size]])
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see [[HPL2/Tutorials/ShowScreenImage()#Placement|Placement]])
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
# ''afFadeIn'' - The time, in seconds, to fade in the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])
# ''afFadeOut'' - The time, in seconds, to fade out the image (see [[HPL2/Tutorials/ShowScreenImage()#Timing|Timing]])

=Size=
* Note that the ''afScale'' argument is ''not'' actually the scale of the image: it is the ''size in pixels''. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively.
* If the size is specified, the image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.
* If the size is given as -1 (or any number less than 0) then the actual pixel size and shape of the image file.

=Placement=
* The origin of the screen-space is the centre. This means that [0, 0] is the centre of the screen regardless of screen resolution, and regardless of ''abUseRelativeCoordinates''.
* The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go.
* If ''abUseRelativeCoordinates'' is ''false'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as actual pixels''.
* If ''abUseRelativeCoordinates'' is ''true'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as a fraction of the screen resolution width or height''.
* The relative co-ordinates still use the centre of the screen as the origin, so the top-left corner of the screen is [-0.5, -0.5] and the bottom-right corner is [0.5, 0.5]. Any relative co-ordinate greater than 0.5 will put the image outside of the screen.

=Timing=
* The total time that the image will be displayed is ''afFadeIn'' + ''afDuration'' + ''afFadeOut''.
* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
* Calling ShowScreenImage() again will replace the current image, regardless of duration or fade times.

=Examples=
<syntaxhighlight lang="c++">
// Centred:
ShowScreenImage("image.dds", -150.0f, -150.0f, 300.0f, false, 3.0f, 0.0f, 0.0f);
// Size: 300 x 300 pixels
// Placement: centred on the screen (image-origin is placed image-size/2 from the screen-origin)
// Timing: 3 seconds, no fading

// From top-left:
ShowScreenImage("image.dds", -0.45f, -0.45f, -1.0f, true, 2.0f, 1.0f, 2.0f);
// Size: original pixel size and shape of the image file
// Placement: near the top-left corner, with a 5% margin relative to the screen size
// Timing: 5 seconds, including fading

// From top-centre:
ShowScreenImage("image.dds", -0.48f, 0.0f, 100.0f, true, 0.0f, 2.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-centre, with a 2% margin relative to the screen size
// Timing: 4 seconds, fading out immediately after fading in

// Bottom-right - not reliable
ShowScreenImage("image.dds", 0.25f, 0.25f, 270.0f, true, 1.0f, 1.0f, 1.0f);
// With a screen resolution of 1920 x 1080, this would fit neatly into the bottom-right 1/16 of the screen (1080 / 4 = 270).
// Unfortunately, if the resolution was lower, it would not fit on the screen. And if the resolution was higher, it would not reach the edges.

// Full-screen kinda... top-left focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom left with lower resolutions.
// At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

// Full-screen kinda... centre focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would stay on the centre of the screen, whatever the resolution.
// At lower resolutions all the edges would be cropped. At higher resolutions it would not fill the screen.
</syntaxhighlight>

=Conclusion=
There are lots of things you can do with ShowScreenImage() if you use it creatively!

...But if you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

HPL2/AMFP/ScriptFunctions

2024-01-04T17:17:02Z

Mrbehemo: Added link to ShowScreenImage() tutorial

== Engine scripts ==

A list of script functions available in A Machine For Pigs (that are not present in The Dark Descent). Many of TDD's scripts are available in AMFP, but not all. Some are replaced by ones listed below, and others are removed.

{{note|'''NOTE:''' This page is partially incomplete. Some arguments for the functions listed here have unknown effects. If you wish to contribute, feel free to test them. It's also possible there are additional script functions not listed here that exist within the engine.}}

----

=== General ===

<syntaxhighlight lang="cpp">
void CheckPoint(string@& asName, string@& asStartArea, string@& asFunction, string@& asTextCat, string@& asTextEntry, const bool abPlayerLimbo);
</syntaxhighlight>

Creates a check point where the player will respawn if they die. '''Callback syntax:'''<code>void MyFunc(string &in asName, int alCount)</code>
This function replaces TDD's <code>CheckPoint()</code>.

# ''asName'' - The internal name of the callback
# ''asStartArea'' - The name of the PlayerStartArea to respawn at
# ''asFunction'' - The name of the callback function to run
# ''asTextCat'' - The name of the .lang file category (SEEMS UNUSED)
# ''asTextEntry'' - The name of the .lang file entry (SEEMS UNUSED)
# ''abPlayerLimbo'' - Whether to put the player into a state of "limbo" upon death. In limbo, the death occurs normally, but once the screen fades to black, it remains so until <code>ReleasePlayerFromLimbo()</code> is called. Player is still controllable during death.
<syntaxhighlight lang="cpp">
void ReleasePlayerFromLimbo();
</syntaxhighlight>

Respawns the player if stuck in "limbo". Limbo can be enabled with ''CheckPoint''. Limbo is the state between life and death. The player enters limbo upon dying but won't respawn until this function is called.

<syntaxhighlight lang="cpp">
void PlayScriptedAnimation(string@& asEntity, string@& asAnimation, const bool abLoop);
</syntaxhighlight>

Plays an animation that has been added to an entity through the Model Editor. Similar to ''PlayEnemyAnimation''.

# asEntity - Internal name of the entity
# asAnimation - The animation name inside the entity
# abLoop - Whether to loop the animation or play it only once

=== Screen effects ===

<syntaxhighlight lang="cpp">
void ShowScreenImage(string@& asImageFile, int alX, int alY, const float afUnknown1, const bool abUnknown2, const float afDuration, const float afFadeInTime, const float afFadeOutTime);
</syntaxhighlight>

Shows a 2D image on the screen. Originally used for showing the intro logo during a sequence.

May work similarly to the [[HPL2/Tutorials/ShowScreenImage()|ATTD 1.5 ShowScreenImage()]].

# ''asImageFile'' - The image file to show. Does not have to be pow2 (although it gives a warning if not)
# ''alX -'' The X position of the top left corner, starting from the center of the screen. Use negative half of the width of the image to center it.
# ''alY -'' The Y position of the top left corner, starting from the center of the screen.
# ''afUnknown1'' - Unsure what this is. Any value 0 or greater results in the image not showing up, so use -1
# ''abUnknown2'' - Unsure what this is. If set to true, image does not display, so use false
# ''afDuration'' - How long, in seconds, the image displays. This does not include fade times
# ''afFadeInTime'' - How long, in seconds, the fade in spends
# ''afFadeOutTime'' - How long, in seconds, the fade out spends

=== Journal ===

<syntaxhighlight lang="cpp">
void AddHint(string& asNameAndTextEntry, string@& asImage);
</syntaxhighlight>

Adds a hint to the player's journal. This function replaces TDD's ''AddDiary''.

# ''asNameAndTextEntry'' - The .lang text entry of the hint. The entry must be in category "Journal" and use the format Hint_MyHint_Name for the title and Hint_MyHint_Text for the body, where MyHint replaces the value you put in this argument.
# ''asImage'' - This argument does not seem to be used. Presumed to be for displaying an image but possibly removed functionality. All existing occurrences are empty.
<syntaxhighlight lang="cpp">
void SetJournalDisabled(const bool abDisabled);
</syntaxhighlight>

Disables the player's ability to open their journal.

# ''abDisabled'' - True to disable, false to enable again
=== Player ===

<syntaxhighlight lang="c++">
void SetLanternFlickerActive(const bool abActive);
</syntaxhighlight>

Enables/disables the flicker effect for the lantern's light.

# ''abActive'' - True to flicker, false to not flicker
<syntaxhighlight lang="c++">
void SetPlayerInfection(const float afAmount);
</syntaxhighlight>

Sets the [[:hpl2:machine_for_pigs:infection|infection]] level for the player. Infection replaces sanity from TDD and acts similar, however it goes from 0-100 instead of 100-0. An infection level above approximately 20 will affect the player's ability to move. Infection level above 80 will kill the player. Infection slowly decreases over time, unless high enough. This function replaces TDD's ''SetPlayerSanity''.

# ''afAmount'' - The level of infection to set
<syntaxhighlight lang="c++">
void AddPlayerInfection(const float afAmount);
</syntaxhighlight>

Adds an amount of infection to the player's current amount. This function replaces TDD's ''AddPlayerSanity''.

# afAmount - The amount to add

<syntaxhighlight lang="cpp">
float GetPlayerInfection();
</syntaxhighlight>

Returns the amount of infection the player currently has. This function replaces TDD's ''GetPlayerSanity''.

<syntaxhighlight lang="c++">
void FadePlayerPitchTo(const float afPitch, const float afDeaccelleration, const float afSpeed);
</syntaxhighlight>

Moves the player's pitch (up and down rotation).

# ''afPitch'' - The target pitch to move towards. 0 = straight forward. Clamped to range: -70 to +70.
# ''afDeaccelleration'' - The deaccelleration when nearing the target pitch. A low value makes a slow change.
# ''afSpeed'' - The speed of the movement. Speed is affected by deaccelleration.
<syntaxhighlight lang="c++">
void SetPlayerUsesDragFootsteps(const bool abX);
</syntaxhighlight>

Sets whether the player's footstep sounds are replaced with "drag" versions. Some surface materials do not have drag steps, and will therefore play no footstep sounds.

# abX - Whether to use "drag" step sounds

=== Entities ===

<syntaxhighlight lang="c++">
void SetPhysicsAutoDisable(string@& asEntity, const bool abDisabled);
</syntaxhighlight>

Does… something. Not immediately apparent. Is only used on chandeliers in the campaign.

# ''asEntity'' - The entity to affect
# ''abDisabled'' - Whether this effect auto disables or not
<syntaxhighlight lang="c++">
void SetLampFlickerActive(string@& asLamp, const bool abActive);
</syntaxhighlight>

Enables a flickering effect on a Lamp-type entity.

# ''asLamp'' - The lamp entity
# ''abActive'' - Whether to enable flicker
<syntaxhighlight lang="c++">
void StartPhoneRinging(string@& asEntity);
</syntaxhighlight>

Enables a PhoneBox-type entity to start ringing. A ringing phone box can be interacted with to play some audio files. After interacting, the phone will stop ringing.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
void StopPhoneRinging(string@& asEntity)
</syntaxhighlight>

Stops a ringing PhoneBox-type entity.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
bool GetEntityActive(string@& asEntity);
</syntaxhighlight>

Returns whether an entity in the level is active or not.

# ''asEntity'' - The entity to check
<syntaxhighlight lang="c++">
void StopPropAnimation(string@& asProp);
</syntaxhighlight>

Stops the animation currently playing on a prop. Animations can be started with ''PlayPropAnimation''.

# ''asProp'' - The name of the entity/prop
<syntaxhighlight lang="c++">
void SetPropAnimationPosition(string@& asProp, const float afPosition);
</syntaxhighlight>

Jumps to a specifc point in an animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The entity that is being animated
# ''afPosition'' - The time within the animation, in seconds, to jump to
<syntaxhighlight lang="c++">
void SetSwingDoorOpenAmount(string@& asEntity, const float afOpenAmount, const float afTime, const bool abUnknown);
</syntaxhighlight>

Sets the open amount for a swing door.

# ''asEntity'' - The SwingDoor entity
# ''afOpenAmount'' - The new amount state to set. Range: 0 - 1
# ''afTime'' - The time in seconds until the door has changed state
# ''abUnknown'' - Unsure what this does. If set to true, nothing happens (?), so use false.
<syntaxhighlight lang="c++">
void FadeLampTo(string@& asEntity, const uint alR, const uint alG, const uint alB, const uint alA, int alRadius, const double afTime);
</syntaxhighlight>

Fades a Lamp-type entity's light to another color. This function uses integers for color values instead of floats, which is a little odd. Likewise, it uses a double floating point for the last argument instead of a regular one.

# ''asEntity'' - The lamp to change
# ''alR'' - Red value (appropriate values are 0 - 10)
# ''alG'' - Green value (appropriate values are 0 - 10)
# ''alB'' - Blue value (appropriate values are 0 - 10)
# ''alA'' - Alpha value (has no effect?)
# ''alRadius'' - The new radius to use (affects illumination strength)
# ''afTime'' - Time in seconds until the light properties have changed
<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOn(string@& asEntity, const bool abX);
</syntaxhighlight>

Changes whether a Button-type entity can be toggled.

# ''asEntity'' - The button entity
# ''abX'' - Whether it can be switched on
<syntaxhighlight lang="c++">
void CreateEntityAtArea(string@& asName, string@& asFile, string@& asArea, const bool abUnknown, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Creates an entity at an area with the specified offsets and rotation. This function replaces TDD's ''CreateEntityAtArea''.

# ''asName'' - The internal name of the created entity
# ''asFile'' - The file for the entity (extension .ent)
# ''asArea'' - The area to create entity at
# ''abUnknown'' - Not sure. Only true is used in the campaign. Seemingly has no effect
# ''afOffsetX'' - The offset along the X axis in units
# ''afOffsetY'' - The offset along the Y axis in units
# ''afOffsetZ'' - The offset along the Z axis in units
# ''afRotX'' - The rotation on the X axis in degrees
# ''afRotY'' - The rotation on the Y axis in degrees
# ''afRotZ'' - The rotation on the Z axis in degrees
<syntaxhighlight lang="c++">
void AttachPropToBone(string@& asProp, string@& asEntity, string@& asBone, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Attaches a prop to a specific bone within another entity. You can inspect bones in the Model Editor. Note: Offsets and rotations are local to the bone and relative to its rotation.

# ''asProp'' - The prop to attach
# ''asEntity'' - The entity that holds the bone to attach to
# ''asBone'' - The bone within the entity to attach to
# ''afOffsetX'' - Offset along the X axis
# ''afOffsetY'' - Offset along the Y axis
# ''afOffsetZ'' - Offset along the Z axis
# ''afRotX'' - Rotation along the X axis
# ''afRotY'' - Rotation along the Y axis
# ''afRotZ'' - Rotation along the Z axis
<syntaxhighlight lang="c++">
void DetachPropFromBone(string@& asProp);
</syntaxhighlight>

Detaches an attached prop. Note: When detached, physics are not automatically enabled on the prop.

# ''asProp'' - The attached prop
<syntaxhighlight lang="c++">
void AttachAreaToProp(string@& asArea, string@& asProp, const float afUnknown);
</syntaxhighlight>

Attaches an area to a prop, however testing has not yielded any useful results. Originally used to attach a liquid area to a movable water plane entity in the sewers map.

# ''asArea'' - The area to attach
# ''asProp'' - The prop to attach area to
# ''alUnknown'' - Unknown float value
=== Sounds ===

<syntaxhighlight lang="c++">
void AddEffectVoice2(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 2 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 2 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice3(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 3 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 3 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice4(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 4 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 4 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice5(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 5 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 5 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice6(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 6 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 6 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice7(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, string@& asTextEntry7, const float afStartTime7, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 7 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 7 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''asTextEntry7'' - The seventh .lang subtitle entry
# ''afStartTime7 ''- The time to wait until the seventh subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
=== Enemies ===

<syntaxhighlight lang="c++">
void AddEnemyPatrolNode(string@& asEnemy, string@& asPathNode, const float afWaitTime, string@& asAnimation, const bool abUnknown);
</syntaxhighlight>

Adds a patrol node to the enemy's walking path. A path is restarted from the beginning when the final node is reached. Note: Inputting an invalid animation in asAnimation at the final node will make the enemy wait there indefinitely. This function replaces TDD's AddEnemyPatrolNode.

# ''asEnemy'' - The name of the enemy
# ''asPathNode'' - Internal name of path node
# ''afWaitTime'' - The time, in seconds, the enemy waits at this node before continuing. Note: A time of 0.0f does not seem to skip waiting, use 0.01f instead if you want the enemy to immediately continue to the next node.
# ''asAnimation'' - The animation to play on the enemy when they arrive at this path node. Animations can be found in the Model Editor. Leave empty to play no special animation (uses default Idle animation). Note: If the animation lasts longer than afWaitTime, the enemy waits until the animation is complete before continuing the path.
# ''abUnknown'' - Unknown variable. Only false is ever used in the campaign. If set to true, seems to affect how animations are played, however they seem to just stutter or loop.
<syntaxhighlight lang="c++">
void SetEnemyMoveType(string@& asEnemy, string@& asMoveType);
</syntaxhighlight>

Changes how an enemy moves.

# ''asEnemy'' - The name of the enemy
# ''asMoveType'' - The type to change to. Type can be "WalkBiped", "RunBiped", "ChargeBiped", "Idle"
<syntaxhighlight lang="c++">
void SetManPigType(string@& asEnemy, string@& asType);
</syntaxhighlight>

Sets the type for a ManPig enemy. It is unknown whether this function does anything or if it's just left over from an earlier state of the game. Only "Freddy" is used as the type, but supposedly it should also accept "Rod" and "Jane".

# ''asEnemy'' - The ManPig enemy.
# ''asType'' - The type to set. Type can be "Freddy", "Rod", "Jane"
The three types allegedly describe three different personality types for the AI, according to Peter Howell in [https://researchportal.port.ac.uk/portal/files/3364888/PeterHowell_PhD.pdf his PhD, section 7.4.4].

Extract:

''The initial design of the game’s enemy artificial intelligence system contained three unique sets of behavioural controls. There was only one visual enemy style, however every enemy agent in the game would be assigned one of three possible ‘personalities’, referred to in the game’s code as the ‘Rod’, ‘Jane’ and ‘Freddy’ personality types. These personalities each had a different set of behavioural rules, thus allowing enemy agents that may otherwise appear identical to behave very differently to one another.''

{| class="wikitable sortable" border=1
!Enemy Agent Personality Type !!Primary Behavioural Traits |
|-
| Rod || – Will maintain a 'safe' distance to the player-character. – unable to do so, will approach player character, investigate them (by getting close and smelling them), before continuing its patrol.
|-
| Jane || – Will maintain a ‘safe’ distance from player-character, whilst observing the player-character’s movements. – If unable to maintain ‘safe’ distance, will panic and flee. – If cornered and unable to flee, will attack and knock player-character to floor, then flee. – Will only attack and kill player-character as a last resort.
|-
| Freddy || – Will actively hunt the player-character. – Will attack and kill them if given the opportunity.
|-
|}

<syntaxhighlight lang="c++">
void PlayEnemyAnimation(string@& asEnemy, string@& asAnimation, const bool abLoop, const float afDelay);
</syntaxhighlight>

Plays a specific animation for an enemy.

# ''asEnemy'' - Internal name of the enemy (asterisk is allowed)
# ''asAnimation'' - The name of an animation registered to the enemy
# ''abLoop'' - Whether the animation loops
# ''afDelay'' - Seems to affect how the animation plays out. A higher value makes the animation slower, although it seems to also skip some keyframes or perhaps merge them, making the animation look incorrect. Experiment to see what works based on the animation.
<syntaxhighlight lang="c++">
void ChangeEnemyPose(string@& asEnemy, string@& asPose);
</syntaxhighlight>

Changes the pose for an enemy. Can be either "Biped" or "Quadruped".

# ''asEnemy'' - Internal name of the enemy
# ''asPose'' - The pose to change to
<syntaxhighlight lang="c++">
void ForceEnemyWaitState(string@& asEnemy);
</syntaxhighlight>

Forces the enemy's AI to change the state to "Wait" which makes the enemy wait for a short while before continuing its' normal actions. An enemy without patrol nodes defaults to the "Wait" state. Otherwise, if patrol nodes are added, the enemy will continue the path after waiting is done.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
void SetEnemyBlind(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can see the player if they are within visible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is blind
<syntaxhighlight lang="c++">
void SetEnemyDeaf(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can hear the player make sound if they are within audible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is deaf
<syntaxhighlight lang="c++">
bool GetPlayerCanSeeEnemy(string@& asEnemy);
</syntaxhighlight>

Returns whether the enemy is within visible range of the player.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
float GetEnemyPlayerDistance(string@& asEnemy);
</syntaxhighlight>

Returns the distance (in HPL units) between the enemy and the player.

# asEnemy - Internal name of the enemy

=== Particles ===

<syntaxhighlight lang="c++">
void SetParticleSystemActive(string@& asParticleSystem, const bool abActive);
</syntaxhighlight>

Pauses a particle system in its current frame. The paused particle system remains frozen at this frame until reactivated or destroyed.

# ''asParticleSystem'' - The name of the particle system
# ''abActive'' - False to pause, true to unpause
<syntaxhighlight lang="c++">
void DestroyParticleSystemInstantly(string@& asParticleSystem);
</syntaxhighlight>

Destroys a particle system and any existing particles already emitted from it. Similar to ''DestroyParticleSystem'', except that one will not destroy the existing particles and rather let them live out their lives. This function will cut all particles' lives short.

# ''asParticleSystem'' - The PS to destroy

HPL2/AMFP/ScriptFunctions

2024-01-04T17:15:27Z

Mrbehemo: Undo revision 6684 by Mrbehemo (talk)

== Engine scripts ==

A list of script functions available in A Machine For Pigs (that are not present in The Dark Descent). Many of TDD's scripts are available in AMFP, but not all. Some are replaced by ones listed below, and others are removed.

{{note|'''NOTE:''' This page is partially incomplete. Some arguments for the functions listed here have unknown effects. If you wish to contribute, feel free to test them. It's also possible there are additional script functions not listed here that exist within the engine.}}

----

=== General ===

<syntaxhighlight lang="cpp">
void CheckPoint(string@& asName, string@& asStartArea, string@& asFunction, string@& asTextCat, string@& asTextEntry, const bool abPlayerLimbo);
</syntaxhighlight>

Creates a check point where the player will respawn if they die. '''Callback syntax:'''<code>void MyFunc(string &in asName, int alCount)</code>
This function replaces TDD's <code>CheckPoint()</code>.

# ''asName'' - The internal name of the callback
# ''asStartArea'' - The name of the PlayerStartArea to respawn at
# ''asFunction'' - The name of the callback function to run
# ''asTextCat'' - The name of the .lang file category (SEEMS UNUSED)
# ''asTextEntry'' - The name of the .lang file entry (SEEMS UNUSED)
# ''abPlayerLimbo'' - Whether to put the player into a state of "limbo" upon death. In limbo, the death occurs normally, but once the screen fades to black, it remains so until <code>ReleasePlayerFromLimbo()</code> is called. Player is still controllable during death.
<syntaxhighlight lang="cpp">
void ReleasePlayerFromLimbo();
</syntaxhighlight>

Respawns the player if stuck in "limbo". Limbo can be enabled with ''CheckPoint''. Limbo is the state between life and death. The player enters limbo upon dying but won't respawn until this function is called.

<syntaxhighlight lang="cpp">
void PlayScriptedAnimation(string@& asEntity, string@& asAnimation, const bool abLoop);
</syntaxhighlight>

Plays an animation that has been added to an entity through the Model Editor. Similar to ''PlayEnemyAnimation''.

# asEntity - Internal name of the entity
# asAnimation - The animation name inside the entity
# abLoop - Whether to loop the animation or play it only once

=== Screen effects ===

<syntaxhighlight lang="cpp">
void ShowScreenImage(string@& asImageFile, int alX, int alY, const float afUnknown1, const bool abUnknown2, const float afDuration, const float afFadeInTime, const float afFadeOutTime);
</syntaxhighlight>

Shows a 2D image on the screen. Originally used for showing the intro logo during a sequence.

# ''asImageFile'' - The image file to show. Does not have to be pow2 (although it gives a warning if not)
# ''alX -'' The X position of the top left corner, starting from the center of the screen. Use negative half of the width of the image to center it.
# ''alY -'' The Y position of the top left corner, starting from the center of the screen.
# ''afUnknown1'' - Unsure what this is. Any value 0 or greater results in the image not showing up, so use -1
# ''abUnknown2'' - Unsure what this is. If set to true, image does not display, so use false
# ''afDuration'' - How long, in seconds, the image displays. This does not include fade times
# ''afFadeInTime'' - How long, in seconds, the fade in spends
# ''afFadeOutTime'' - How long, in seconds, the fade out spends
=== Journal ===

<syntaxhighlight lang="cpp">
void AddHint(string& asNameAndTextEntry, string@& asImage);
</syntaxhighlight>

Adds a hint to the player's journal. This function replaces TDD's ''AddDiary''.

# ''asNameAndTextEntry'' - The .lang text entry of the hint. The entry must be in category "Journal" and use the format Hint_MyHint_Name for the title and Hint_MyHint_Text for the body, where MyHint replaces the value you put in this argument.
# ''asImage'' - This argument does not seem to be used. Presumed to be for displaying an image but possibly removed functionality. All existing occurrences are empty.
<syntaxhighlight lang="cpp">
void SetJournalDisabled(const bool abDisabled);
</syntaxhighlight>

Disables the player's ability to open their journal.

# ''abDisabled'' - True to disable, false to enable again
=== Player ===

<syntaxhighlight lang="c++">
void SetLanternFlickerActive(const bool abActive);
</syntaxhighlight>

Enables/disables the flicker effect for the lantern's light.

# ''abActive'' - True to flicker, false to not flicker
<syntaxhighlight lang="c++">
void SetPlayerInfection(const float afAmount);
</syntaxhighlight>

Sets the [[:hpl2:machine_for_pigs:infection|infection]] level for the player. Infection replaces sanity from TDD and acts similar, however it goes from 0-100 instead of 100-0. An infection level above approximately 20 will affect the player's ability to move. Infection level above 80 will kill the player. Infection slowly decreases over time, unless high enough. This function replaces TDD's ''SetPlayerSanity''.

# ''afAmount'' - The level of infection to set
<syntaxhighlight lang="c++">
void AddPlayerInfection(const float afAmount);
</syntaxhighlight>

Adds an amount of infection to the player's current amount. This function replaces TDD's ''AddPlayerSanity''.

# afAmount - The amount to add

<syntaxhighlight lang="cpp">
float GetPlayerInfection();
</syntaxhighlight>

Returns the amount of infection the player currently has. This function replaces TDD's ''GetPlayerSanity''.

<syntaxhighlight lang="c++">
void FadePlayerPitchTo(const float afPitch, const float afDeaccelleration, const float afSpeed);
</syntaxhighlight>

Moves the player's pitch (up and down rotation).

# ''afPitch'' - The target pitch to move towards. 0 = straight forward. Clamped to range: -70 to +70.
# ''afDeaccelleration'' - The deaccelleration when nearing the target pitch. A low value makes a slow change.
# ''afSpeed'' - The speed of the movement. Speed is affected by deaccelleration.
<syntaxhighlight lang="c++">
void SetPlayerUsesDragFootsteps(const bool abX);
</syntaxhighlight>

Sets whether the player's footstep sounds are replaced with "drag" versions. Some surface materials do not have drag steps, and will therefore play no footstep sounds.

# abX - Whether to use "drag" step sounds

=== Entities ===

<syntaxhighlight lang="c++">
void SetPhysicsAutoDisable(string@& asEntity, const bool abDisabled);
</syntaxhighlight>

Does… something. Not immediately apparent. Is only used on chandeliers in the campaign.

# ''asEntity'' - The entity to affect
# ''abDisabled'' - Whether this effect auto disables or not
<syntaxhighlight lang="c++">
void SetLampFlickerActive(string@& asLamp, const bool abActive);
</syntaxhighlight>

Enables a flickering effect on a Lamp-type entity.

# ''asLamp'' - The lamp entity
# ''abActive'' - Whether to enable flicker
<syntaxhighlight lang="c++">
void StartPhoneRinging(string@& asEntity);
</syntaxhighlight>

Enables a PhoneBox-type entity to start ringing. A ringing phone box can be interacted with to play some audio files. After interacting, the phone will stop ringing.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
void StopPhoneRinging(string@& asEntity)
</syntaxhighlight>

Stops a ringing PhoneBox-type entity.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
bool GetEntityActive(string@& asEntity);
</syntaxhighlight>

Returns whether an entity in the level is active or not.

# ''asEntity'' - The entity to check
<syntaxhighlight lang="c++">
void StopPropAnimation(string@& asProp);
</syntaxhighlight>

Stops the animation currently playing on a prop. Animations can be started with ''PlayPropAnimation''.

# ''asProp'' - The name of the entity/prop
<syntaxhighlight lang="c++">
void SetPropAnimationPosition(string@& asProp, const float afPosition);
</syntaxhighlight>

Jumps to a specifc point in an animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The entity that is being animated
# ''afPosition'' - The time within the animation, in seconds, to jump to
<syntaxhighlight lang="c++">
void SetSwingDoorOpenAmount(string@& asEntity, const float afOpenAmount, const float afTime, const bool abUnknown);
</syntaxhighlight>

Sets the open amount for a swing door.

# ''asEntity'' - The SwingDoor entity
# ''afOpenAmount'' - The new amount state to set. Range: 0 - 1
# ''afTime'' - The time in seconds until the door has changed state
# ''abUnknown'' - Unsure what this does. If set to true, nothing happens (?), so use false.
<syntaxhighlight lang="c++">
void FadeLampTo(string@& asEntity, const uint alR, const uint alG, const uint alB, const uint alA, int alRadius, const double afTime);
</syntaxhighlight>

Fades a Lamp-type entity's light to another color. This function uses integers for color values instead of floats, which is a little odd. Likewise, it uses a double floating point for the last argument instead of a regular one.

# ''asEntity'' - The lamp to change
# ''alR'' - Red value (appropriate values are 0 - 10)
# ''alG'' - Green value (appropriate values are 0 - 10)
# ''alB'' - Blue value (appropriate values are 0 - 10)
# ''alA'' - Alpha value (has no effect?)
# ''alRadius'' - The new radius to use (affects illumination strength)
# ''afTime'' - Time in seconds until the light properties have changed
<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOn(string@& asEntity, const bool abX);
</syntaxhighlight>

Changes whether a Button-type entity can be toggled.

# ''asEntity'' - The button entity
# ''abX'' - Whether it can be switched on
<syntaxhighlight lang="c++">
void CreateEntityAtArea(string@& asName, string@& asFile, string@& asArea, const bool abUnknown, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Creates an entity at an area with the specified offsets and rotation. This function replaces TDD's ''CreateEntityAtArea''.

# ''asName'' - The internal name of the created entity
# ''asFile'' - The file for the entity (extension .ent)
# ''asArea'' - The area to create entity at
# ''abUnknown'' - Not sure. Only true is used in the campaign. Seemingly has no effect
# ''afOffsetX'' - The offset along the X axis in units
# ''afOffsetY'' - The offset along the Y axis in units
# ''afOffsetZ'' - The offset along the Z axis in units
# ''afRotX'' - The rotation on the X axis in degrees
# ''afRotY'' - The rotation on the Y axis in degrees
# ''afRotZ'' - The rotation on the Z axis in degrees
<syntaxhighlight lang="c++">
void AttachPropToBone(string@& asProp, string@& asEntity, string@& asBone, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Attaches a prop to a specific bone within another entity. You can inspect bones in the Model Editor. Note: Offsets and rotations are local to the bone and relative to its rotation.

# ''asProp'' - The prop to attach
# ''asEntity'' - The entity that holds the bone to attach to
# ''asBone'' - The bone within the entity to attach to
# ''afOffsetX'' - Offset along the X axis
# ''afOffsetY'' - Offset along the Y axis
# ''afOffsetZ'' - Offset along the Z axis
# ''afRotX'' - Rotation along the X axis
# ''afRotY'' - Rotation along the Y axis
# ''afRotZ'' - Rotation along the Z axis
<syntaxhighlight lang="c++">
void DetachPropFromBone(string@& asProp);
</syntaxhighlight>

Detaches an attached prop. Note: When detached, physics are not automatically enabled on the prop.

# ''asProp'' - The attached prop
<syntaxhighlight lang="c++">
void AttachAreaToProp(string@& asArea, string@& asProp, const float afUnknown);
</syntaxhighlight>

Attaches an area to a prop, however testing has not yielded any useful results. Originally used to attach a liquid area to a movable water plane entity in the sewers map.

# ''asArea'' - The area to attach
# ''asProp'' - The prop to attach area to
# ''alUnknown'' - Unknown float value
=== Sounds ===

<syntaxhighlight lang="c++">
void AddEffectVoice2(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 2 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 2 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice3(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 3 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 3 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice4(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 4 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 4 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice5(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 5 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 5 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice6(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 6 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 6 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice7(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, string@& asTextEntry7, const float afStartTime7, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 7 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 7 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''asTextEntry7'' - The seventh .lang subtitle entry
# ''afStartTime7 ''- The time to wait until the seventh subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
=== Enemies ===

<syntaxhighlight lang="c++">
void AddEnemyPatrolNode(string@& asEnemy, string@& asPathNode, const float afWaitTime, string@& asAnimation, const bool abUnknown);
</syntaxhighlight>

Adds a patrol node to the enemy's walking path. A path is restarted from the beginning when the final node is reached. Note: Inputting an invalid animation in asAnimation at the final node will make the enemy wait there indefinitely. This function replaces TDD's AddEnemyPatrolNode.

# ''asEnemy'' - The name of the enemy
# ''asPathNode'' - Internal name of path node
# ''afWaitTime'' - The time, in seconds, the enemy waits at this node before continuing. Note: A time of 0.0f does not seem to skip waiting, use 0.01f instead if you want the enemy to immediately continue to the next node.
# ''asAnimation'' - The animation to play on the enemy when they arrive at this path node. Animations can be found in the Model Editor. Leave empty to play no special animation (uses default Idle animation). Note: If the animation lasts longer than afWaitTime, the enemy waits until the animation is complete before continuing the path.
# ''abUnknown'' - Unknown variable. Only false is ever used in the campaign. If set to true, seems to affect how animations are played, however they seem to just stutter or loop.
<syntaxhighlight lang="c++">
void SetEnemyMoveType(string@& asEnemy, string@& asMoveType);
</syntaxhighlight>

Changes how an enemy moves.

# ''asEnemy'' - The name of the enemy
# ''asMoveType'' - The type to change to. Type can be "WalkBiped", "RunBiped", "ChargeBiped", "Idle"
<syntaxhighlight lang="c++">
void SetManPigType(string@& asEnemy, string@& asType);
</syntaxhighlight>

Sets the type for a ManPig enemy. It is unknown whether this function does anything or if it's just left over from an earlier state of the game. Only "Freddy" is used as the type, but supposedly it should also accept "Rod" and "Jane".

# ''asEnemy'' - The ManPig enemy.
# ''asType'' - The type to set. Type can be "Freddy", "Rod", "Jane"
The three types allegedly describe three different personality types for the AI, according to Peter Howell in [https://researchportal.port.ac.uk/portal/files/3364888/PeterHowell_PhD.pdf his PhD, section 7.4.4].

Extract:

''The initial design of the game’s enemy artificial intelligence system contained three unique sets of behavioural controls. There was only one visual enemy style, however every enemy agent in the game would be assigned one of three possible ‘personalities’, referred to in the game’s code as the ‘Rod’, ‘Jane’ and ‘Freddy’ personality types. These personalities each had a different set of behavioural rules, thus allowing enemy agents that may otherwise appear identical to behave very differently to one another.''

{| class="wikitable sortable" border=1
!Enemy Agent Personality Type !!Primary Behavioural Traits |
|-
| Rod || – Will maintain a 'safe' distance to the player-character. – unable to do so, will approach player character, investigate them (by getting close and smelling them), before continuing its patrol.
|-
| Jane || – Will maintain a ‘safe’ distance from player-character, whilst observing the player-character’s movements. – If unable to maintain ‘safe’ distance, will panic and flee. – If cornered and unable to flee, will attack and knock player-character to floor, then flee. – Will only attack and kill player-character as a last resort.
|-
| Freddy || – Will actively hunt the player-character. – Will attack and kill them if given the opportunity.
|-
|}

<syntaxhighlight lang="c++">
void PlayEnemyAnimation(string@& asEnemy, string@& asAnimation, const bool abLoop, const float afDelay);
</syntaxhighlight>

Plays a specific animation for an enemy.

# ''asEnemy'' - Internal name of the enemy (asterisk is allowed)
# ''asAnimation'' - The name of an animation registered to the enemy
# ''abLoop'' - Whether the animation loops
# ''afDelay'' - Seems to affect how the animation plays out. A higher value makes the animation slower, although it seems to also skip some keyframes or perhaps merge them, making the animation look incorrect. Experiment to see what works based on the animation.
<syntaxhighlight lang="c++">
void ChangeEnemyPose(string@& asEnemy, string@& asPose);
</syntaxhighlight>

Changes the pose for an enemy. Can be either "Biped" or "Quadruped".

# ''asEnemy'' - Internal name of the enemy
# ''asPose'' - The pose to change to
<syntaxhighlight lang="c++">
void ForceEnemyWaitState(string@& asEnemy);
</syntaxhighlight>

Forces the enemy's AI to change the state to "Wait" which makes the enemy wait for a short while before continuing its' normal actions. An enemy without patrol nodes defaults to the "Wait" state. Otherwise, if patrol nodes are added, the enemy will continue the path after waiting is done.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
void SetEnemyBlind(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can see the player if they are within visible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is blind
<syntaxhighlight lang="c++">
void SetEnemyDeaf(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can hear the player make sound if they are within audible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is deaf
<syntaxhighlight lang="c++">
bool GetPlayerCanSeeEnemy(string@& asEnemy);
</syntaxhighlight>

Returns whether the enemy is within visible range of the player.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
float GetEnemyPlayerDistance(string@& asEnemy);
</syntaxhighlight>

Returns the distance (in HPL units) between the enemy and the player.

# asEnemy - Internal name of the enemy

=== Particles ===

<syntaxhighlight lang="c++">
void SetParticleSystemActive(string@& asParticleSystem, const bool abActive);
</syntaxhighlight>

Pauses a particle system in its current frame. The paused particle system remains frozen at this frame until reactivated or destroyed.

# ''asParticleSystem'' - The name of the particle system
# ''abActive'' - False to pause, true to unpause
<syntaxhighlight lang="c++">
void DestroyParticleSystemInstantly(string@& asParticleSystem);
</syntaxhighlight>

Destroys a particle system and any existing particles already emitted from it. Similar to ''DestroyParticleSystem'', except that one will not destroy the existing particles and rather let them live out their lives. This function will cut all particles' lives short.

# ''asParticleSystem'' - The PS to destroy

HPL2/AMFP/ScriptFunctions

2024-01-04T17:14:50Z

Mrbehemo: Edited notes for ShowScreenImage() and added a link to tutorial.

== Engine scripts ==

A list of script functions available in A Machine For Pigs (that are not present in The Dark Descent). Many of TDD's scripts are available in AMFP, but not all. Some are replaced by ones listed below, and others are removed.

{{note|'''NOTE:''' This page is partially incomplete. Some arguments for the functions listed here have unknown effects. If you wish to contribute, feel free to test them. It's also possible there are additional script functions not listed here that exist within the engine.}}

----

=== General ===

<syntaxhighlight lang="cpp">
void CheckPoint(string@& asName, string@& asStartArea, string@& asFunction, string@& asTextCat, string@& asTextEntry, const bool abPlayerLimbo);
</syntaxhighlight>

Creates a check point where the player will respawn if they die. '''Callback syntax:'''<code>void MyFunc(string &in asName, int alCount)</code>
This function replaces TDD's <code>CheckPoint()</code>.

# ''asName'' - The internal name of the callback
# ''asStartArea'' - The name of the PlayerStartArea to respawn at
# ''asFunction'' - The name of the callback function to run
# ''asTextCat'' - The name of the .lang file category (SEEMS UNUSED)
# ''asTextEntry'' - The name of the .lang file entry (SEEMS UNUSED)
# ''abPlayerLimbo'' - Whether to put the player into a state of "limbo" upon death. In limbo, the death occurs normally, but once the screen fades to black, it remains so until <code>ReleasePlayerFromLimbo()</code> is called. Player is still controllable during death.
<syntaxhighlight lang="cpp">
void ReleasePlayerFromLimbo();
</syntaxhighlight>

Respawns the player if stuck in "limbo". Limbo can be enabled with ''CheckPoint''. Limbo is the state between life and death. The player enters limbo upon dying but won't respawn until this function is called.

<syntaxhighlight lang="cpp">
void PlayScriptedAnimation(string@& asEntity, string@& asAnimation, const bool abLoop);
</syntaxhighlight>

Plays an animation that has been added to an entity through the Model Editor. Similar to ''PlayEnemyAnimation''.

# asEntity - Internal name of the entity
# asAnimation - The animation name inside the entity
# abLoop - Whether to loop the animation or play it only once

=== Screen effects ===

<syntaxhighlight lang="cpp">
void ShowScreenImage(string@& asImageFile, int alX, int alY, const float afUnknown1, const bool abUnknown2, const float afDuration, const float afFadeInTime, const float afFadeOutTime);
</syntaxhighlight>

Shows a 2D image on the screen. Originally used for showing the intro logo during a sequence.
See [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] in the ATTD tutorials section for more information.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)
# ''afX'' - The X position of the image
# ''afY'' - The Y position of the image
# ''afScale'' - The size of the image in pixels (not scale), or original image size if negative
# ''abUseRelativeCoordinates'' - Whether X and Y are relative to the screen resoltion, or pixel co-ordinates if not
# ''afDuration'' - The duration that the image is displayed for
# ''afFadeIn'' - The time, in seconds, to fade in the image
# ''afFadeOut'' - The time, in seconds, to fade out the image

=== Journal ===

<syntaxhighlight lang="cpp">
void AddHint(string& asNameAndTextEntry, string@& asImage);
</syntaxhighlight>

Adds a hint to the player's journal. This function replaces TDD's ''AddDiary''.

# ''asNameAndTextEntry'' - The .lang text entry of the hint. The entry must be in category "Journal" and use the format Hint_MyHint_Name for the title and Hint_MyHint_Text for the body, where MyHint replaces the value you put in this argument.
# ''asImage'' - This argument does not seem to be used. Presumed to be for displaying an image but possibly removed functionality. All existing occurrences are empty.
<syntaxhighlight lang="cpp">
void SetJournalDisabled(const bool abDisabled);
</syntaxhighlight>

Disables the player's ability to open their journal.

# ''abDisabled'' - True to disable, false to enable again
=== Player ===

<syntaxhighlight lang="c++">
void SetLanternFlickerActive(const bool abActive);
</syntaxhighlight>

Enables/disables the flicker effect for the lantern's light.

# ''abActive'' - True to flicker, false to not flicker
<syntaxhighlight lang="c++">
void SetPlayerInfection(const float afAmount);
</syntaxhighlight>

Sets the [[:hpl2:machine_for_pigs:infection|infection]] level for the player. Infection replaces sanity from TDD and acts similar, however it goes from 0-100 instead of 100-0. An infection level above approximately 20 will affect the player's ability to move. Infection level above 80 will kill the player. Infection slowly decreases over time, unless high enough. This function replaces TDD's ''SetPlayerSanity''.

# ''afAmount'' - The level of infection to set
<syntaxhighlight lang="c++">
void AddPlayerInfection(const float afAmount);
</syntaxhighlight>

Adds an amount of infection to the player's current amount. This function replaces TDD's ''AddPlayerSanity''.

# afAmount - The amount to add

<syntaxhighlight lang="cpp">
float GetPlayerInfection();
</syntaxhighlight>

Returns the amount of infection the player currently has. This function replaces TDD's ''GetPlayerSanity''.

<syntaxhighlight lang="c++">
void FadePlayerPitchTo(const float afPitch, const float afDeaccelleration, const float afSpeed);
</syntaxhighlight>

Moves the player's pitch (up and down rotation).

# ''afPitch'' - The target pitch to move towards. 0 = straight forward. Clamped to range: -70 to +70.
# ''afDeaccelleration'' - The deaccelleration when nearing the target pitch. A low value makes a slow change.
# ''afSpeed'' - The speed of the movement. Speed is affected by deaccelleration.
<syntaxhighlight lang="c++">
void SetPlayerUsesDragFootsteps(const bool abX);
</syntaxhighlight>

Sets whether the player's footstep sounds are replaced with "drag" versions. Some surface materials do not have drag steps, and will therefore play no footstep sounds.

# abX - Whether to use "drag" step sounds

=== Entities ===

<syntaxhighlight lang="c++">
void SetPhysicsAutoDisable(string@& asEntity, const bool abDisabled);
</syntaxhighlight>

Does… something. Not immediately apparent. Is only used on chandeliers in the campaign.

# ''asEntity'' - The entity to affect
# ''abDisabled'' - Whether this effect auto disables or not
<syntaxhighlight lang="c++">
void SetLampFlickerActive(string@& asLamp, const bool abActive);
</syntaxhighlight>

Enables a flickering effect on a Lamp-type entity.

# ''asLamp'' - The lamp entity
# ''abActive'' - Whether to enable flicker
<syntaxhighlight lang="c++">
void StartPhoneRinging(string@& asEntity);
</syntaxhighlight>

Enables a PhoneBox-type entity to start ringing. A ringing phone box can be interacted with to play some audio files. After interacting, the phone will stop ringing.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
void StopPhoneRinging(string@& asEntity)
</syntaxhighlight>

Stops a ringing PhoneBox-type entity.

# ''asEntity'' - The PhoneBox entity
<syntaxhighlight lang="c++">
bool GetEntityActive(string@& asEntity);
</syntaxhighlight>

Returns whether an entity in the level is active or not.

# ''asEntity'' - The entity to check
<syntaxhighlight lang="c++">
void StopPropAnimation(string@& asProp);
</syntaxhighlight>

Stops the animation currently playing on a prop. Animations can be started with ''PlayPropAnimation''.

# ''asProp'' - The name of the entity/prop
<syntaxhighlight lang="c++">
void SetPropAnimationPosition(string@& asProp, const float afPosition);
</syntaxhighlight>

Jumps to a specifc point in an animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The entity that is being animated
# ''afPosition'' - The time within the animation, in seconds, to jump to
<syntaxhighlight lang="c++">
void SetSwingDoorOpenAmount(string@& asEntity, const float afOpenAmount, const float afTime, const bool abUnknown);
</syntaxhighlight>

Sets the open amount for a swing door.

# ''asEntity'' - The SwingDoor entity
# ''afOpenAmount'' - The new amount state to set. Range: 0 - 1
# ''afTime'' - The time in seconds until the door has changed state
# ''abUnknown'' - Unsure what this does. If set to true, nothing happens (?), so use false.
<syntaxhighlight lang="c++">
void FadeLampTo(string@& asEntity, const uint alR, const uint alG, const uint alB, const uint alA, int alRadius, const double afTime);
</syntaxhighlight>

Fades a Lamp-type entity's light to another color. This function uses integers for color values instead of floats, which is a little odd. Likewise, it uses a double floating point for the last argument instead of a regular one.

# ''asEntity'' - The lamp to change
# ''alR'' - Red value (appropriate values are 0 - 10)
# ''alG'' - Green value (appropriate values are 0 - 10)
# ''alB'' - Blue value (appropriate values are 0 - 10)
# ''alA'' - Alpha value (has no effect?)
# ''alRadius'' - The new radius to use (affects illumination strength)
# ''afTime'' - Time in seconds until the light properties have changed
<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOn(string@& asEntity, const bool abX);
</syntaxhighlight>

Changes whether a Button-type entity can be toggled.

# ''asEntity'' - The button entity
# ''abX'' - Whether it can be switched on
<syntaxhighlight lang="c++">
void CreateEntityAtArea(string@& asName, string@& asFile, string@& asArea, const bool abUnknown, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Creates an entity at an area with the specified offsets and rotation. This function replaces TDD's ''CreateEntityAtArea''.

# ''asName'' - The internal name of the created entity
# ''asFile'' - The file for the entity (extension .ent)
# ''asArea'' - The area to create entity at
# ''abUnknown'' - Not sure. Only true is used in the campaign. Seemingly has no effect
# ''afOffsetX'' - The offset along the X axis in units
# ''afOffsetY'' - The offset along the Y axis in units
# ''afOffsetZ'' - The offset along the Z axis in units
# ''afRotX'' - The rotation on the X axis in degrees
# ''afRotY'' - The rotation on the Y axis in degrees
# ''afRotZ'' - The rotation on the Z axis in degrees
<syntaxhighlight lang="c++">
void AttachPropToBone(string@& asProp, string@& asEntity, string@& asBone, const float afOffsetX, const float afOffsetY, const float afOffsetZ, const float afRotX, const float afRotY, const float afRotZ);
</syntaxhighlight>

Attaches a prop to a specific bone within another entity. You can inspect bones in the Model Editor. Note: Offsets and rotations are local to the bone and relative to its rotation.

# ''asProp'' - The prop to attach
# ''asEntity'' - The entity that holds the bone to attach to
# ''asBone'' - The bone within the entity to attach to
# ''afOffsetX'' - Offset along the X axis
# ''afOffsetY'' - Offset along the Y axis
# ''afOffsetZ'' - Offset along the Z axis
# ''afRotX'' - Rotation along the X axis
# ''afRotY'' - Rotation along the Y axis
# ''afRotZ'' - Rotation along the Z axis
<syntaxhighlight lang="c++">
void DetachPropFromBone(string@& asProp);
</syntaxhighlight>

Detaches an attached prop. Note: When detached, physics are not automatically enabled on the prop.

# ''asProp'' - The attached prop
<syntaxhighlight lang="c++">
void AttachAreaToProp(string@& asArea, string@& asProp, const float afUnknown);
</syntaxhighlight>

Attaches an area to a prop, however testing has not yielded any useful results. Originally used to attach a liquid area to a movable water plane entity in the sewers map.

# ''asArea'' - The area to attach
# ''asProp'' - The prop to attach area to
# ''alUnknown'' - Unknown float value
=== Sounds ===

<syntaxhighlight lang="c++">
void AddEffectVoice2(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 2 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 2 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice3(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 3 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 3 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice4(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 4 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 4 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice5(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 5 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 5 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice6(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 6 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 6 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
<syntaxhighlight lang="c++">
void AddEffectVoice7(string@& asVoiceFile, string@& asEffectFile, string@& asTextCat, string@& asTextEntry1, const float afStartTime1, string@& asTextEntry2, const float afStartTime2, string@& asTextEntry3, const float afStartTime3, string@& asTextEntry4, const float afStartTime4, string@& asTextEntry5, const float afStartTime5, string@& asTextEntry6, const float afStartTime6, string@& asTextEntry7, const float afStartTime7, const bool abUsePosition, string@& asPosEntity, const float afMinDistance, const float afMaxDistance);
</syntaxhighlight>

Plays an audio file with 7 consecutive subtitles.

# ''asVoiceFile'' - The entire voice file to play (intended to include 7 sections)
# ''asEffectFile'' - The background effect file to play during voices. Leave empty for no extra effect
# ''asTextCat'' - The .lang text category for the subtitles
# ''asTextEntry1'' - The first .lang subtitle entry
# ''afStartTime1'' - The time to wait until the first subtitle starts
# ''asTextEntry2'' - The second .lang subtitle entry
# ''afStartTime2'' - The time to wait until the second subtitle starts
# ''asTextEntry3'' - The third .lang subtitle entry
# ''afStartTime3'' - The time to wait until the third subtitle starts
# ''asTextEntry4'' - The fourth .lang subtitle entry
# ''afStartTime4'' - The time to wait until the fourth subtitle starts
# ''asTextEntry5'' - The fifth .lang subtitle entry
# ''afStartTime5'' - The time to wait until the fifth subtitle starts
# ''asTextEntry6'' - The sixth .lang subtitle entry
# ''afStartTime6'' - The time to wait until the sixth subtitle starts
# ''asTextEntry7'' - The seventh .lang subtitle entry
# ''afStartTime7 ''- The time to wait until the seventh subtitle starts
# ''abUsePosition'' - Whether to use 3D to play the sound from an entity
# ''asPosEntity'' - The entity to play the sound from. If empty, plays from player
# ''afMinDistance'' - The minimum distance required between the player and the entity in order to hear the audio
# ''afMaxDistance'' - The maximum distance allowed between the player and the entity in order to hear the audio
=== Enemies ===

<syntaxhighlight lang="c++">
void AddEnemyPatrolNode(string@& asEnemy, string@& asPathNode, const float afWaitTime, string@& asAnimation, const bool abUnknown);
</syntaxhighlight>

Adds a patrol node to the enemy's walking path. A path is restarted from the beginning when the final node is reached. Note: Inputting an invalid animation in asAnimation at the final node will make the enemy wait there indefinitely. This function replaces TDD's AddEnemyPatrolNode.

# ''asEnemy'' - The name of the enemy
# ''asPathNode'' - Internal name of path node
# ''afWaitTime'' - The time, in seconds, the enemy waits at this node before continuing. Note: A time of 0.0f does not seem to skip waiting, use 0.01f instead if you want the enemy to immediately continue to the next node.
# ''asAnimation'' - The animation to play on the enemy when they arrive at this path node. Animations can be found in the Model Editor. Leave empty to play no special animation (uses default Idle animation). Note: If the animation lasts longer than afWaitTime, the enemy waits until the animation is complete before continuing the path.
# ''abUnknown'' - Unknown variable. Only false is ever used in the campaign. If set to true, seems to affect how animations are played, however they seem to just stutter or loop.
<syntaxhighlight lang="c++">
void SetEnemyMoveType(string@& asEnemy, string@& asMoveType);
</syntaxhighlight>

Changes how an enemy moves.

# ''asEnemy'' - The name of the enemy
# ''asMoveType'' - The type to change to. Type can be "WalkBiped", "RunBiped", "ChargeBiped", "Idle"
<syntaxhighlight lang="c++">
void SetManPigType(string@& asEnemy, string@& asType);
</syntaxhighlight>

Sets the type for a ManPig enemy. It is unknown whether this function does anything or if it's just left over from an earlier state of the game. Only "Freddy" is used as the type, but supposedly it should also accept "Rod" and "Jane".

# ''asEnemy'' - The ManPig enemy.
# ''asType'' - The type to set. Type can be "Freddy", "Rod", "Jane"
The three types allegedly describe three different personality types for the AI, according to Peter Howell in [https://researchportal.port.ac.uk/portal/files/3364888/PeterHowell_PhD.pdf his PhD, section 7.4.4].

Extract:

''The initial design of the game’s enemy artificial intelligence system contained three unique sets of behavioural controls. There was only one visual enemy style, however every enemy agent in the game would be assigned one of three possible ‘personalities’, referred to in the game’s code as the ‘Rod’, ‘Jane’ and ‘Freddy’ personality types. These personalities each had a different set of behavioural rules, thus allowing enemy agents that may otherwise appear identical to behave very differently to one another.''

{| class="wikitable sortable" border=1
!Enemy Agent Personality Type !!Primary Behavioural Traits |
|-
| Rod || – Will maintain a 'safe' distance to the player-character. – unable to do so, will approach player character, investigate them (by getting close and smelling them), before continuing its patrol.
|-
| Jane || – Will maintain a ‘safe’ distance from player-character, whilst observing the player-character’s movements. – If unable to maintain ‘safe’ distance, will panic and flee. – If cornered and unable to flee, will attack and knock player-character to floor, then flee. – Will only attack and kill player-character as a last resort.
|-
| Freddy || – Will actively hunt the player-character. – Will attack and kill them if given the opportunity.
|-
|}

<syntaxhighlight lang="c++">
void PlayEnemyAnimation(string@& asEnemy, string@& asAnimation, const bool abLoop, const float afDelay);
</syntaxhighlight>

Plays a specific animation for an enemy.

# ''asEnemy'' - Internal name of the enemy (asterisk is allowed)
# ''asAnimation'' - The name of an animation registered to the enemy
# ''abLoop'' - Whether the animation loops
# ''afDelay'' - Seems to affect how the animation plays out. A higher value makes the animation slower, although it seems to also skip some keyframes or perhaps merge them, making the animation look incorrect. Experiment to see what works based on the animation.
<syntaxhighlight lang="c++">
void ChangeEnemyPose(string@& asEnemy, string@& asPose);
</syntaxhighlight>

Changes the pose for an enemy. Can be either "Biped" or "Quadruped".

# ''asEnemy'' - Internal name of the enemy
# ''asPose'' - The pose to change to
<syntaxhighlight lang="c++">
void ForceEnemyWaitState(string@& asEnemy);
</syntaxhighlight>

Forces the enemy's AI to change the state to "Wait" which makes the enemy wait for a short while before continuing its' normal actions. An enemy without patrol nodes defaults to the "Wait" state. Otherwise, if patrol nodes are added, the enemy will continue the path after waiting is done.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
void SetEnemyBlind(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can see the player if they are within visible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is blind
<syntaxhighlight lang="c++">
void SetEnemyDeaf(string@& asEnemy, const bool abX);
</syntaxhighlight>

Sets whether the enemy can hear the player make sound if they are within audible range.

# ''asEnemy'' - Internal name of the enemy
# ''abX'' - Whether enemy is deaf
<syntaxhighlight lang="c++">
bool GetPlayerCanSeeEnemy(string@& asEnemy);
</syntaxhighlight>

Returns whether the enemy is within visible range of the player.

# ''asEnemy'' - Internal name of the enemy
<syntaxhighlight lang="c++">
float GetEnemyPlayerDistance(string@& asEnemy);
</syntaxhighlight>

Returns the distance (in HPL units) between the enemy and the player.

# asEnemy - Internal name of the enemy

=== Particles ===

<syntaxhighlight lang="c++">
void SetParticleSystemActive(string@& asParticleSystem, const bool abActive);
</syntaxhighlight>

Pauses a particle system in its current frame. The paused particle system remains frozen at this frame until reactivated or destroyed.

# ''asParticleSystem'' - The name of the particle system
# ''abActive'' - False to pause, true to unpause
<syntaxhighlight lang="c++">
void DestroyParticleSystemInstantly(string@& asParticleSystem);
</syntaxhighlight>

Destroys a particle system and any existing particles already emitted from it. Similar to ''DestroyParticleSystem'', except that one will not destroy the existing particles and rather let them live out their lives. This function will cut all particles' lives short.

# ''asParticleSystem'' - The PS to destroy

HPL2/Engine Scripts

2024-01-04T17:14:16Z

Mrbehemo:

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

#''afStep''- time elapsed since the last frame. Multiply speeds, distances etc. by this argument to avoid framerate dependence issues (for example: if you move something in this function with constant speed, it will move faster on computers which run the game with high FPS and slower on computers with low FPS).

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen. See [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] in the tutorials section for more information.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)
# ''afX'' - The X position of the image
# ''afY'' - The Y position of the image
# ''afScale'' - The size of the image in pixels (not scale), or original image size if negative
# ''abUseRelativeCoordinates'' - Whether X and Y are relative to the screen resoltion, or pixel co-ordinates if not
# ''afDuration'' - The duration that the image is displayed for
# ''afFadeIn'' - The time, in seconds, to fade in the image
# ''afFadeOut'' - The time, in seconds, to fade out the image

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Tutorials/ShowScreenImage()

2024-01-04T17:11:23Z

Mrbehemo:

=Introduction=
ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

=Function=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see Size)
# ''afX'' - The X position of the image (see Placement)
# ''afY'' - The Y position of the image (see Placement)
# ''afScale'' - The size of the image in pixels, or original image size if negative (see Size)
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see Timing)
# ''afFadeIn'' - The time, in seconds, to fade in the image (see Timing)
# ''afFadeOut'' - The time, in seconds, to fade out the image (see Timing)

=Size=
* Note that the ''afScale'' argument is ''not'' actually the scale of the image: it is the ''size in pixels''. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively.
* If the size is specified, the image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.
* If the size is given as -1 (or any number less than 0) then the actual pixel size and shape of the image file.

=Placement=
* The origin of the screen-space is the centre. This means that [0, 0] is the centre of the screen regardless of screen resolution, and regardless of ''abUseRelativeCoordinates''.
* The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go.
* If ''abUseRelativeCoordinates'' is ''false'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as actual pixels''.
* If ''abUseRelativeCoordinates'' is ''true'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as a fraction of the screen resolution width or height''.
* The relative co-ordinates still use the centre of the screen as the origin, so the top-left corner of the screen is [-0.5, -0.5] and the bottom-right corner is [0.5, 0.5]. Any relative co-ordinate greater than 0.5 will put the image outside of the screen.

=Timing=
* The total time that the image will be displayed is ''afFadeIn'' + ''afDuration'' + ''afFadeOut''.
* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
* Calling ShowScreenImage() again will replace the current image, regardless of duration or fade times.

=Examples=
<syntaxhighlight lang="c++">
// Centred:
ShowScreenImage("image.dds", -150.0f, -150.0f, 300.0f, false, 3.0f, 0.0f, 0.0f);
// Size: 300 x 300 pixels
// Placement: centred on the screen (image-origin is placed image-size/2 from the screen-origin)
// Timing: 3 seconds, no fading

// From top-left:
ShowScreenImage("image.dds", -0.45f, -0.45f, -1.0f, true, 2.0f, 1.0f, 2.0f);
// Size: original pixel size and shape of the image file
// Placement: near the top-left corner, with a 5% margin relative to the screen size
// Timing: 5 seconds, including fading

// From top-centre:
ShowScreenImage("image.dds", -0.48f, 0.0f, 100.0f, true, 0.0f, 2.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-centre, with a 2% margin relative to the screen size
// Timing: 4 seconds, fading out immediately after fading in

// Bottom-right - not reliable
ShowScreenImage("image.dds", 0.25f, 0.25f, 270.0f, true, 1.0f, 1.0f, 1.0f);
// With a screen resolution of 1920 x 1080, this would fit neatly into the bottom-right 1/16 of the screen (1080 / 4 = 270).
// Unfortunately, if the resolution was lower, it would not fit on the screen. And if the resolution was higher, it would not reach the edges.

// Full-screen kinda... top-left focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom left with lower resolutions.
// At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

// Full-screen kinda... centre focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would stay on the centre of the screen, whatever the resolution.
// At lower resolutions all the edges would be cropped. At higher resolutions it would not fill the screen.
</syntaxhighlight>

=Conclusion=
There are lots of things you can do with ShowScreenImage() if you use it creatively!

...But if you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

HPL2/Engine Scripts

2024-01-04T17:11:05Z

Mrbehemo:

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

#''afStep''- time elapsed since the last frame. Multiply speeds, distances etc. by this argument to avoid framerate dependence issues (for example: if you move something in this function with constant speed, it will move faster on computers which run the game with high FPS and slower on computers with low FPS).

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen. See [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] in the tutorials section for more information.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The size of the image in pixels (not scale), or original image size if negative

''abUseRelativeCoordinates'' - Whether X and Y are relative to the screen resoltion, or pixel co-ordinates if not

''afDuration'' - The duration that the image is displayed for

''afFadeIn'' - The time, in seconds, to fade in the image

''afFadeOut'' - The time, in seconds, to fade out the image

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Tutorials/ShowScreenImage()

2024-01-04T17:10:09Z

Mrbehemo: Added -1 size option.

=Introduction=
ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

=Function=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see Size)
# ''afX'' - The X position of the image (see Placement)
# ''afY'' - The Y position of the image (see Placement)
# ''afScale'' - The size of the image in pixels (see Size)
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see Timing)
# ''afFadeIn'' - The time, in seconds, to fade in the image (see Timing)
# ''afFadeOut'' - The time, in seconds, to fade out the image (see Timing)

=Size=
* Note that the ''afScale'' argument is ''not'' actually the scale of the image: it is the ''size in pixels''. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively.
* If the size is specified, the image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.
* If the size is given as -1 (or any number less than 0) then the actual pixel size and shape of the image file.

=Placement=
* The origin of the screen-space is the centre. This means that [0, 0] is the centre of the screen regardless of screen resolution, and regardless of ''abUseRelativeCoordinates''.
* The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go.
* If ''abUseRelativeCoordinates'' is ''false'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as actual pixels''.
* If ''abUseRelativeCoordinates'' is ''true'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as a fraction of the screen resolution width or height''.
* The relative co-ordinates still use the centre of the screen as the origin, so the top-left corner of the screen is [-0.5, -0.5] and the bottom-right corner is [0.5, 0.5]. Any relative co-ordinate greater than 0.5 will put the image outside of the screen.

=Timing=
* The total time that the image will be displayed is ''afFadeIn'' + ''afDuration'' + ''afFadeOut''.
* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
* Calling ShowScreenImage() again will replace the current image, regardless of duration or fade times.

=Examples=
<syntaxhighlight lang="c++">
// Centred:
ShowScreenImage("image.dds", -150.0f, -150.0f, 300.0f, false, 3.0f, 0.0f, 0.0f);
// Size: 300 x 300 pixels
// Placement: centred on the screen (image-origin is placed image-size/2 from the screen-origin)
// Timing: 3 seconds, no fading

// From top-left:
ShowScreenImage("image.dds", -0.45f, -0.45f, -1.0f, true, 2.0f, 1.0f, 2.0f);
// Size: original pixel size and shape of the image file
// Placement: near the top-left corner, with a 5% margin relative to the screen size
// Timing: 5 seconds, including fading

// From top-centre:
ShowScreenImage("image.dds", -0.48f, 0.0f, 100.0f, true, 0.0f, 2.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-centre, with a 2% margin relative to the screen size
// Timing: 4 seconds, fading out immediately after fading in

// Bottom-right - not reliable
ShowScreenImage("image.dds", 0.25f, 0.25f, 270.0f, true, 1.0f, 1.0f, 1.0f);
// With a screen resolution of 1920 x 1080, this would fit neatly into the bottom-right 1/16 of the screen (1080 / 4 = 270).
// Unfortunately, if the resolution was lower, it would not fit on the screen. And if the resolution was higher, it would not reach the edges.

// Full-screen kinda... top-left focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom left with lower resolutions.
// At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

// Full-screen kinda... centre focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would stay on the centre of the screen, whatever the resolution.
// At lower resolutions all the edges would be cropped. At higher resolutions it would not fill the screen.
</syntaxhighlight>

=Conclusion=
There are lots of things you can do with ShowScreenImage() if you use it creatively!

...But if you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

HPL2/Engine Scripts

2024-01-04T17:03:17Z

Mrbehemo:

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

#''afStep''- time elapsed since the last frame. Multiply speeds, distances etc. by this argument to avoid framerate dependence issues (for example: if you move something in this function with constant speed, it will move faster on computers which run the game with high FPS and slower on computers with low FPS).

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen. See [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] in the tutorials section for more information.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The size of the image in pixels (not scale)

''abUseRelativeCoordinates'' - Whether X and Y are relative to the screen resoltion, or pixel co-ordinates if not

''afDuration'' - The duration that the image is displayed for

''afFadeIn'' - The time, in seconds, to fade in the image

''afFadeOut'' - The time, in seconds, to fade out the image

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Engine Scripts

2024-01-04T17:02:36Z

Mrbehemo: Edited notes for ShowScreenImage() and added a link to tutorial.

{{TocRight}}

This page documents all scripts available in Amnesia: The Dark Descent.

{{note|'''Note''': Some of the functions require the Amnesia 1.3 or 1.5 update. Steam and other online store copies should be automatically updated. Other copies can get 1.3 [http://www.frictionalgames.com/forum/thread-24334.html here].}}

== Directives ==

First off, <code>#include "file.hps"</code> can be used to programmatically merge together multiple separate files to make organizing scripts easier.

{{ReqVer|1.5}}

==Engine scripts==
===Main===

The following functions are the main hps functions that the HPL2 engine looks to run on certain events - similar to the C++ int main() function.

<syntaxhighlight lang="cpp">
void OnStart();
</syntaxhighlight>

The function that runs when the map is loaded for the first time.

<syntaxhighlight lang="c++">
void OnEnter();
</syntaxhighlight>

The function that runs whenever the player enters a map.

<syntaxhighlight lang="c++">
void OnLeave();
</syntaxhighlight>

The function that runs when the player leaves a map.

<syntaxhighlight lang="c++">
void OnGameStart();
</syntaxhighlight>

This function is found in the global.hps file and the inventory.hps file, and is run when the game is first started by the player (ie via "Start New Game").

<syntaxhighlight lang="c++">
void OnUpdate(float afStep);
</syntaxhighlight>
{{ReqVer|1.5}}

This function is executed for every game update or "tick". Can be used for rapid-firing updates instead of looping timers. Keep in mind that this can affect game performance if not used with care.

#''afStep''- time elapsed since the last frame. Multiply speeds, distances etc. by this argument to avoid framerate dependence issues (for example: if you move something in this function with constant speed, it will move faster on computers which run the game with high FPS and slower on computers with low FPS).

===General===

<syntaxhighlight lang="c++">
float RandFloat(float afMin, float afMax);
</syntaxhighlight>

Generates a random float.

#''afMin ''- minimum value
#''afMax ''- maximum value
<syntaxhighlight lang="c++">
int RandInt(int alMin, int alMax);
</syntaxhighlight>

Generates a random int. Note: the maximum value is ''inclusive'' - the RandInt() function may return this value.

#''alMin ''- minimum value
#''alMax ''- maximum value
<syntaxhighlight lang="c++">
bool StringContains(string& asString, string& asSubString);
</syntaxhighlight>

Checks whether a string contains the specified string. Example: searching for "hello" in "hello world" would return '''true'''.

#''asString ''- the string to check
#''asSubString ''- the string to search for
<syntaxhighlight lang="cpp">
string& StringSub(string& asString, int alStart, int alCount);
</syntaxhighlight>

Returns the substring in a string. Example: in the string "frictional games rocks", using 4 as ''alStart'' and 6 as ''alCount'' would return '''"tional"'''.

#''asString ''- the string
#''alStart ''- start position in the string
#''alCount ''- amount of characters
<syntaxhighlight lang="c++">
int StringToInt(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns an integer converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
float StringToFloat(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a float converted from a string, else returns 0.

#''asString'' - String to convert.
<syntaxhighlight lang="c++">
bool StringToBool(string&in asString);
</syntaxhighlight>

{{ReqVer|1.3}}

If possible, returns a boolean converted from a string, else returns false.

#''asString'' - String to convert.

===Mathematical Operations===

<syntaxhighlight lang="c++">
float MathSin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathCos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathTan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAsin(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc sine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAcos(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc cosine of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the arc tangent of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathAtan2(float afX, float afY);
</syntaxhighlight>

{{ReqVer|1.3}}

Calculates and returns the arc tangent of the specified values.

#''afX'' - First value to operate.
#''afY'' - Second value to operate.
<syntaxhighlight lang="c++">
float MathSqrt(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the square root of the specified value.

#''afX'' - Value to operate.
<syntaxhighlight lang="c++">
float MathPow(float afBase, float afExp);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the value of afBase raised to the power of afExp.

#''afBase'' - The base value.
#''afExp'' - Value to calculate the base with.
<syntaxhighlight lang="c++">
float MathMin(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the lowest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathMax(float afA, float afB);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the highest value.

#''afA'' - First value.
#''afB'' - Second value.
<syntaxhighlight lang="c++">
float MathClamp(float afX, float afMin, float afMax);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns afX clamped between afMin and afMax. If afX < afMin, returns afMin, and if afX > afMax, returns afMax.

#''afX'' - The value to clamp.
#''afMin'' - The minimum value to clamp afX with.
#''afMax'' - The maximum value to clamp afX with.
<syntaxhighlight lang="c++">
float MathAbs(float afX);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the absolute value.

#''afX'' - Value to operate.

===Debugging===

<syntaxhighlight lang="cpp">
void Print(string& asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string& asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a string to the debug console.

#''asString ''- the string to print
#''abCheckForDuplicates ''- if true, the string won't be printed more than once on screen until it disappears
<syntaxhighlight lang="c++">
void ProgLog(string& asLevel, string& asMessage);
</syntaxhighlight>

Prints an entry to the ProgLog (progression log). ProgLog is a file created in Documents/Amnesia/main (or an FC folder if one is being used). It logs certain events, such us opening the menu or picking up the lantern, as well as the player's state (Health, Sanity, Oil, Tinderboxes, Coins), for the purpose of documenting a tester's playstyle. This function allows to log custom messages.The messages in the ProgLog file are sorted by time elapsed since a map was loaded.

ProgLog has to be enabled for a player profile in ''user_settings.cfg'' before it starts working.

#''asLevel ''- can be "Low", "Medium" or "High". It's a tag which appears in each log entry, for event prioritising.
#''asMessage ''- The custom message to be printed to the log.
<syntaxhighlight lang="c++">
bool ScriptDebugOn();
</syntaxhighlight>

Checks whether the debug mode is enabled. See [[HPL2/Development_Environment|"Setting up Development Environment"]] to setup debug mode on your own computer.

===Variables===
{{warning|Regular variables (int, float, etc.) are '''not''' saved by the game. Using them in important parts of yor script will break it upon loading a game save. In HPL, those variables should only be used for disposable counters, like spawning objects in a "for" loop. For variables which need to be saved, use the wrappers as described below.}}

====Local====

Local variables can be used throughout the same script file.

<syntaxhighlight lang="cpp">
void SetLocalVarInt(string& asName, int alVal);
void AddLocalVarInt(string& asName, int alVal);
int GetLocalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string& asName, float afVal);
void AddLocalVarFloat(string& asName, float afVal);
float GetLocalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string& asName, const string& asVal);
void AddLocalVarString(string& asName, string& asVal);
string& GetLocalVarString(string& asName);
</syntaxhighlight>

====Global====

Global variables can be used throughout several maps and can be accessed by several script files.

<syntaxhighlight lang="c++">
void SetGlobalVarInt(string& asName, int alVal);
void AddGlobalVarInt(string& asName, int alVal);
int GetGlobalVarInt(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string& asName, float afVal);
void AddGlobalVarFloat(string& asName, float afVal);
float GetGlobalVarFloat(string& asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string& asName, const string& asVal);
void AddGlobalVarString(string& asName, string& asVal);
string& GetGlobalVarString(string& asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string& asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS);
</syntaxhighlight>

Creates a particle system on an entity.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntityExt(string& asPSName, string& asPSFile, string& asEntity, bool abSavePS,
float afR, float afG, float afB, float afA, bool abFadeAtDistance, float afFadeMinEnd, float afFadeMinStart,
float afFadeMaxStart, float afFadeMaxEnd);
</syntaxhighlight>

Creates a particle system on an entity, extended method with more options.

#''asPSName ''- internal name
#''asPSFile ''- the particle system to use + extension .ps
#''asEntity ''- the entity to create the particle system at
#''abSavePS ''- determines whether a particle system should "remember" its shown/hidden state, so that this state can be restored when the player revisits the level
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''abFadeAtDistance ''- determines whether a particle system fades from a certain distance on
#''afFadeMinEnd ''- minimum distance at which the particle system stops fading
#''afFadeMinStart ''- minimum distance at which the particle system starts fading
#''afFadeMaxStart ''- maximum distance at which the particle system starts fading
#''afFadeMaxEnd ''- maximum distance at which the particle system stops fading
<syntaxhighlight lang="c++">
void DestroyParticleSystem(string& asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string& asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load. Extension: .snt
<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string& asSoundName, string& asSoundFile, string& asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound on an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use + extension .snt
#''asEntity ''- the entity to create the sound at, can be "Player"
#''afFadeTime ''- time in seconds the sound needs to fade. Avoids enemies hearing the sound if afFadeTime is at least 0.1f
#''abSaveSound ''- if ''true'', a looping sound will "remember" its playback state (currently playing/stopped), and that state will be restored the next time the level is entered. If ''true'', the sound is never attached to the entity! Note that saving should only be used on ''looping sounds''!
<syntaxhighlight lang="c++">
void FadeInSound(string& asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- ?
<syntaxhighlight lang="c++">
void StopSound(string& asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediatly stop the sound
<syntaxhighlight lang="c++">
void PlayMusic(string& asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music to play + extension .ogg
#''abLoop ''- determines whether a music track should loop
#''afVolume ''- volume of the music
#''afFadeTime ''- time in seconds until music reaches full volume
#''alPrio ''- priority of the music. Note that only the music with the highest priority can be heard! 0 - lowest, 1 - higher, etc.
#''abResume'' - if ''true'', playback will be continued from where the track stopped after the call to StopMusic(); if ''false'', the track will be restarted.
<syntaxhighlight lang="c++">
void StopMusic(float afFadeTime, int alPrio);
</syntaxhighlight>

Stops music.

#''afFadeTime ''- time in seconds until music stops
#''alPrio ''- the priority of the music that should stop
<syntaxhighlight lang="c++">
void FadeGlobalSoundVolume(float afDestVolume, float afTime);
</syntaxhighlight>

Influences the global sound volume, that means everything you can hear '''from the world'''. This does not affect music of GUI sounds.

#''afDestVolume ''- desired volume
#''afTime ''- time in seconds until volume reaches desired volume
<syntaxhighlight lang="c++">
void FadeGlobalSoundSpeed(float afDestSpeed, float afTime);
</syntaxhighlight>

Influences the global sound speed.

#''afDestSpeed ''- desired speed
#''afTime ''- time in seconds until volume reaches desired speed

===Lights===

<syntaxhighlight lang="c++">
void SetLightVisible(string& asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string& asLightName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Changes the properties of a light.

#''asLightName ''- internal name
#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
#''afRadius ''- radius of the light. -1 means keeping the radius
#''afTime ''- time in seconds until change is done
<syntaxhighlight lang="c++">
void SetLightFlickerActive(string& asLightName, bool abActive);
</syntaxhighlight>

Activates flickering on a light.

#''asLightName'' - The internal light name
#''abActive'' - true = active, false = inactive

==Game scripts==

===General===

<syntaxhighlight lang="c++">
void StartCredits(string& asMusic, bool abLoopMusic, string& asTextCat, string& asTextEntry, int alEndNum);
</syntaxhighlight>

Starts the end credits screen.

#''asMusic ''- the music to play (including .ogg)
#''abLoopMusic ''- determines whether the music should loop
#''asTextCat ''- the category to be used in the .lang file
#''asTextEntry ''- the entry in the .lang file
#''alEndNum ''- Amnesia has 3 different endings and displays a code at the bottom. Determines which code is displayed. 0-2 will display codes, any other integer will not.
<syntaxhighlight lang="c++">
void StartDemoEnd();
</syntaxhighlight>

Starts the end images that are used in the demo, images are named "demo_end01.jpg", increase the number for each image you want to use. (NEEDS VERIFICATION)

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Save the game to the auto save.

<syntaxhighlight lang="c++">
void CheckPoint (string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry);
</syntaxhighlight>

Sets a checkpoint at which the player will respawn in case he dies. Callback syntax: <code>void MyFunc(string &in asName, int alCount)</code> Count is 0 on the first checkpoint load!

#''asName ''- the internal name
#''asStartPos ''- the name of the StartPos in the editor
#''asCallback ''- the function to call when the player dies/respawns
#''asDeathHintCat ''- the category of the death hint message to be used in the .lang file
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string& asMapName, string& asStartPos, string& asStartSound, string& asEndSound);
</syntaxhighlight>

Immediatly loads another map.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos on the next map
#''asStartSound ''- the sound that is played when the change starts
#''asEndSound ''- the sound that is played when the new map is loaded
<syntaxhighlight lang="c++">
void ClearSavedMaps();
</syntaxhighlight>

Clears the "history" of the save, useful to do when you know the player will not be able to go back anymore. Makes the next save much smaller in size.

<syntaxhighlight lang="c++">
void CreateDataCache();
void DestroyDataCache();
</syntaxhighlight>

This caches all current textures and models and they are not released until destroy is called. If there is already cached data it is destroyed.
Create caches to enable faster loading when going back to a map. Destroy the cache if you know the player won't go back to that map.

<syntaxhighlight lang="c++">
void SetMapDisplayNameEntry(string& asNameEntry);
</syntaxhighlight>

Sets the map name shown in save file names. If none is set NULL is assumed.

#''asNameEntry ''- the entry to display, category must be "Levels"!
<syntaxhighlight lang="c++">
void SetSkyBoxActive(bool abActive);
</syntaxhighlight>

Enables/Disables the skybox.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetSkyBoxTexture(string& asTexture);
</syntaxhighlight>

Sets the texture of the skybox.

#''asTexture'' - The texture file to set. Extension: .dds
<syntaxhighlight lang="c++">
void SetSkyBoxColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the solid color of the skybox rather than a texture.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogActive(bool abActive);
</syntaxhighlight>

Enables/Disables the global fog.

#''abActive'' - true = active, false = inactive
<syntaxhighlight lang="c++">
void SetFogColor(float afR, float afG, float afB, float afA);
</syntaxhighlight>

Sets the color to use for the global fog.

#''afR ''- red value
#''afG ''- green value
#''afB ''- blue value
#''afA ''- alpha value
<syntaxhighlight lang="c++">
void SetFogProperties(float afStart, float afEnd, float afFalloffExp, bool abCulling);
</syntaxhighlight>

Sets the properties for the global fog.

#''afStart ''- how many meters from the camera should the fog begin
#''afEnd ''- how many meters from the camera should the fog reach full thickness
#''afFalloffExp ''- the amount by which the thinkness increases
#''abCulling ''- whether occlusion culling is active for the fog; this prevents objects behind the fog from being loaded
<syntaxhighlight lang="c++">
void SetupLoadScreen(string&asTextCat, string&asTextEntry, int alRandomNum, string&asImageFile);
</syntaxhighlight>

Determines which loading screen will be shown when changing maps.

#''asTextCat ''- the category of the loading text in the .lang file to be shown on the loading screen
#''asTextEntry ''- the entry in the .lang file
#''alRandomNum ''- if greater 1, then it will randomize between 1 and alRandom for each LoadScreen giving entry the suffix XX (eg 01). If < =1 then no suffix is added
#''asImageFile ''- the image to be shown (optional)

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string& asName, float afTime, string& asFunction);
</syntaxhighlight>

Creates a timer which calls a function when it expires. Callback syntax: <code>void MyFunc(string &in asTimer)</code>

#''asName ''- the name of the timer
#''afTime ''- time in seconds
#''asFunction ''- the function to call
<syntaxhighlight lang="c++">
void RemoveTimer(string& asName);
</syntaxhighlight>

Removes a timer, no matter how much time is left.

#''asName'' - the internal name of the timer.
<syntaxhighlight lang="c++">
float GetTimerTimeLeft(string& asName);
</syntaxhighlight>

Returns the time left on a timer.

#''asName'' - the internal name of the timer.

===Screen Effects===

<syntaxhighlight lang="c++">
void FadeOut(float afTime);
</syntaxhighlight>

Fades the screen to black.

''afTime ''- time in seconds until the screen is completly black

<syntaxhighlight lang="c++">
void FadeIn(float afTime);
</syntaxhighlight>

Fades the screen back to normal.

''afTime ''- time in seconds until the screen back to normal

<syntaxhighlight lang="c++">
void FadeImageTrailTo(float afAmount, float afSpeed);
</syntaxhighlight>

Applies the image trail effect to the screen.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeSepiaColorTo(float afAmount, float afSpeed);
</syntaxhighlight>

Makes the screen go dark red.

''afAmount ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void FadeRadialBlurTo(float afSize, float afSpeed);
</syntaxhighlight>

Applies radial blur effects to the screen.

''afSize ''- intensity (default: 0) ''afSpeed ''- time in seconds until full effect

<syntaxhighlight lang="c++">
void SetRadialBlurStartDist(float afStartDist);
</syntaxhighlight>

Determines at which distance the radial blur effects appear.

''afStartDist ''- the distance at which the effect starts

<syntaxhighlight lang="c++">
void StartEffectFlash(float afFadeIn, float afWhite, float afFadeOut);
</syntaxhighlight>

Fades the screen to white.

''afFadeIn ''- time in seconds until screen is white ''afWhite ''- determines to which percentage the screen fades to white (1.0 = completly white) ''afFadeOut ''- time in seconds until screen is back to normal again

<syntaxhighlight lang="c++">
void StartEffectEmotionFlash(string& asTextCat, string& asTextEntry, string& asSound);
</syntaxhighlight>

Fades the screen to white and shows a text message.

''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''asSound ''- the sound to play while fading

<syntaxhighlight lang="c++">
void AddEffectVoice(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry,
bool abUsePosition, string& asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an effect to be played. It is okay to call this many times in order to play many voices in a row. The EffectVoiceOverCallback is not called until ALL voices have finished.

''asVoiceFile ''- the voice to play ''asEffectFile ''- the effect to play ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the text entry in the .lang file ''abUsePosition ''- plays using 3D from the entity, or without 3D ''asPosEntity ''- the entity at which the effect appears ''afMinDistance ''- minimum distance to see the effect ''afMaxDistance ''- maximum distance to see the effect

<syntaxhighlight lang="c++">
void StopAllEffectVoices(float afFadeOutTime);
</syntaxhighlight>

Stops all voices and calls the EffectVoiceOverCallback.

<syntaxhighlight lang="c++">
bool GetEffectVoiceActive();
</syntaxhighlight>

Checks whether EffectVoices are still active.

<syntaxhighlight lang="c++">
void SetEffectVoiceOverCallback(string& asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<syntaxhighlight lang="c++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string& asSPSFile);
void StopPlayerSpawnPS();
</syntaxhighlight>

Continuously spawn regular particle systems (''.ps'') around the player. Particles created by this script carry over from map to map. ''asSPSFile'' - the ''.sps'' file to use. Exemplary ''.sps'' files are located in the ''/misc'' folder in the main game directory. Custom ''.sps'' files can be created by hand in a text editor (see existing ones and mimic how those are written). Since ''StopPlayerSpawnPS()'' doesn't seem to work, to stop an SPS you must create an ''.sps'' file with an empty particle field field and override the old SPS by calling ''StartPlayerSpawnPS'' again.

<syntaxhighlight lang="c++">
void PlayGuiSound(string& asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

''asSoundFile ''- the sound to play (extension is .snt) ''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void StartScreenShake(float afAmount, float afTime, float afFadeInTime, float afFadeOutTime);
</syntaxhighlight>

Shakes the screen.

''afAmount ''- intensity of the shake ''afTime ''- duration of the shake ''afFadeInTime ''- time in seconds until full intensity is reached ''afFadeOutTime ''- time until screen is back to normal

<syntaxhighlight lang="c++">
void SetInDarknessEffectsActive(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the sanity drain and night vision effects while in the darkness.

''bool abX'' - Enable/disable effects.

<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

{{ReqVer|1.5}}

Displays an image file directly onto the screen.

''asImageName'' - The image file to render (.jpg, .png, .tga, .dds)

''afX'' - The X position of the image

''afY'' - The Y position of the image

''afScale'' - The size of the image in pixels (not scale)

''abUseRelativeCoordinates'' - Whether X and Y are relative to the screen resoltion, or pixel co-ordinates if not

''afDuration'' - The duration that the image is displayed for

''afFadeIn'' - The time, in seconds, to fade in the image

''afFadeOut'' - The time, in seconds, to fade out the image

See [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] in the tutorials section for more information.

===Insanity===

<syntaxhighlight lang="c++">
void SetInsanitySetEnabled(string& asSet, bool abX);
</syntaxhighlight>

Determines which InsanitySets are enabled.

''asSet ''- the set ''abX ''- enabled or not

<syntaxhighlight lang="c++">
void StartInsanityEvent(string &in asEventName);
</syntaxhighlight>

{{ReqVer|1.3}}

Starts a specified insanity event.

''asEventName ''- Insanity event to play.

<syntaxhighlight lang="c++">
void StartRandomInsanityEvent();
</syntaxhighlight>

Starts a random insanity event from the available sets.

<syntaxhighlight lang="c++">
void StopCurrentInsanityEvent();
</syntaxhighlight>

{{ReqVer|1.3}}

Stops the currently playing insanity event.

<syntaxhighlight lang="c++">
void InsanityEventIsActive();
</syntaxhighlight>

Checks whether an insanity event is currently in effect… Or so it was supposed to be, but as it doesn't return a value, we can never know [http://wiki.frictionalgames.com/lib/images/smileys/icon_smile.gif?nolink&15x15]

===Player===

Note that the player's maximum health and sanity is 100.

<syntaxhighlight lang="c++">
void SetPlayerActive(bool abActive);
</syntaxhighlight>

Enabled/Disable player controlled movement.

<syntaxhighlight lang="c++">
void ChangePlayerStateToNormal();
</syntaxhighlight>

Sets certain effects back to normal. It can for example make the player drop an item.

<syntaxhighlight lang="c++">
void SetPlayerCrouching(bool abCrouch);
</syntaxhighlight>

Forces the player to crouch.

<syntaxhighlight lang="c++">
void AddPlayerBodyForce(float afX, float afY, float afZ, bool abUseLocalCoords);
</syntaxhighlight>

Pushes the player into a certain direction. Note that you need values above ~2000 to see any effects.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''abUseLocalCoords ''- If true, axes are based on where the player is facing, not the world.

<syntaxhighlight lang="c++">
void ShowPlayerCrossHairIcons(bool abX);
</syntaxhighlight>

Enables/Disables the icons when a player has something in focus.

<syntaxhighlight lang="c++">
void SetPlayerSanity(float afSanity);
void AddPlayerSanity(float afSanity);
float GetPlayerSanity();
</syntaxhighlight>

Modifies/returns the sanity of the player.

<syntaxhighlight lang="c++">
void SetPlayerHealth(float afHealth);
void AddPlayerHealth(float afHealth);
float GetPlayerHealth();
</syntaxhighlight>

Modifies/returns the health of the player.

<syntaxhighlight lang="c++">
void SetPlayerLampOil(float afOil);
void AddPlayerLampOil(float afOil);
float GetPlayerLampOil();
</syntaxhighlight>

Modifies/returns the lamp oil of the player.

<syntaxhighlight lang="c++">
float GetPlayerSpeed();
float GetPlayerYSpeed();
</syntaxhighlight>

Returns the current speed of the player.

<syntaxhighlight lang="c++">
void SetSanityDrainDisabled(bool abX);
</syntaxhighlight>

Enables/Disables sanity drain from darkness, monsters, etc.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a fixed amount.

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

''afAmount ''- amount of sanity damage done ''abUseEffect ''- determines whether an effect is played when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string& asType, bool abSpinHead, bool abLethal);
</syntaxhighlight>

Reduces the health of the player.

''afAmount ''- amount of damage done to health ''asType ''- plays a certain effect on the screen when the damage is dealt (BloodSplat, Claws or Slash) ''abSpinHead ''- changes the camera view when damage is dealt ''abLethal ''- set to true if player can die from given damage

<syntaxhighlight lang="c++">
void FadePlayerFOVMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the field of view of the player. A shorter FOV will create a zoom effect.

''afX ''- multiplier of default FOV (1 is default) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerAspectMulTo(float afX, float afSpeed);
</syntaxhighlight>

Changes the aspect ratio of the player. Basically stretches or narrows the screen horizontally.

''afX ''- multiplier of default aspect (default is 1) ''afSpeed ''- the speed of change between FOV's

<syntaxhighlight lang="c++">
void FadePlayerRollTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Rotates the position of the camera on the player's body.

''afX ''- angle of rotation of head, positive being counter-clockwise ''afSpeedMul ''- speed (possibly acceleration) multiplier of the rotation (default 1, which is really slow) ''afMaxSpeed ''- maximum speed of rotation

<syntaxhighlight lang="c++">
void MovePlayerHeadPos(float afX, float afY, float afZ, float afSpeed, float afSlowDownDist);
</syntaxhighlight>

Changes the position of the camera on the player's body.

''afX ''- amount along the X-axis ''afY ''- amount along the Y-axis ''afZ ''- amount along the Z-axis ''afSpeed ''- speed at which the change happens ''afSlowDownDist ''- distance at which to start slowing down (prevents the head from abruptly stopping)

<syntaxhighlight lang="c++">
void StartPlayerLookAt(string& asEntityName, float afSpeedMul, float afMaxSpeed, string& asAtTargetCallback);
void StopPlayerLookAt();
</syntaxhighlight>

Forces the player to look at a certain entity until StopPlayerLookAt is used.

''asEntityName ''- the entity to look at ''afSpeedMul ''- how fast should the player look at the entity ''afMaxSpeed ''- maximum speed allowed ''asAtTargetCallback ''- function to call when player looks at target

<syntaxhighlight lang="c++">
void SetPlayerMoveSpeedMul(float afMul);
void SetPlayerRunSpeedMul(float afMul);
void SetPlayerLookSpeedMul(float afMul);
</syntaxhighlight>

Changes the player's move/run/look speed. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpForceMul(float afMul);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the player's jump multiplier. Higher values = higher jumps. Default is 1.

<syntaxhighlight lang="c++">
void SetPlayerJumpDisabled(bool abX);
void SetPlayerCrouchDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to jump/crouch.

<syntaxhighlight lang="c++">
void TeleportPlayer(string& asStartPosName);
</syntaxhighlight>

Instantly teleports the player to the target StartPos.

<syntaxhighlight lang="c++">
void SetLanternActive(bool abX, bool abUseEffects);
</syntaxhighlight>

Makes the player use his lantern.

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player currently uses his lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use his lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string& asCallback);
</syntaxhighlight>

Sets the function to call when the player uses his lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Displays a message on the screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- determines how long the message is displayed. If time is < =0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void SetDeathHint(string& asTextCategory, string& asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="c++">
void DisableDeathStartSound();
</syntaxhighlight>

Disables the death sound when the player dies. This must be called directly before player is killed! The variable as soon as player dies too.

<syntaxhighlight lang="">
void MovePlayerForward(float afAmount)
</syntaxhighlight>

"REQUIRES THE 1.2 PATCH: JUSTINE" Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<syntaxhighlight lang="c++">
void SetPlayerFallDamageDisabled(bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables the player's ability to take fall damage.

<syntaxhighlight lang="c++">
void SetPlayerPos(float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the player's position within the level.

''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c++">
float GetPlayerPosX();
float GetPlayerPosY();
float GetPlayerPosZ();
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the player's position within the level on the specified axis.

===Journal===

<syntaxhighlight lang="c++">
void AddNote(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a note to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _Name and _Text and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void AddDiary(string& asNameAndTextEntry, string& asImage);
</syntaxhighlight>

Adds a diary to the player's journal.

''asNameAndTextEntry ''- entries in the .lang file. Must end with _NameX and _TextY whereas X and Y are numbers of the parts (_Name1: first diary, _Text1: first page) and be in category "Journal"! ''asImage ''- the background image to be used

<syntaxhighlight lang="c++">
void ReturnOpenJournal(bool abOpenJournal);
</syntaxhighlight>

Only called in the pickup diary callback! If true the journal displays the entry else not.

===Quests===

<syntaxhighlight lang="c++">
void AddQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos.

''asName ''- the internal name to be used ''asNameAndTextEntry ''- entry in the .lang file. Must start with "Quest_<texthere>_Text”, and be in category “Journal”!

<syntaxhighlight lang="c++">
void CompleteQuest(string& asName, string& asNameAndTextEntry);
</syntaxhighlight>

Completes a quest.

''asName ''- the internal name of the quest ''asNameAndTextEntry ''- entry in the .lang file. Must start with " Quest_<texthere>_Text ”, and be in category “Journal”!

<syntaxhighlight lang="c++">
bool QuestIsCompleted(string& asName);
bool QuestIsAdded(string& asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map.

''alNumberOfQuests ''- Amount of Quests

<syntaxhighlight lang="c++">
void GiveHint(string& asName, string& asMessageCat, string& asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

''asName ''- the internal name ''asMessageCat ''- the category in the .lang file ''asMessageEntry ''- the entry in the .lang file ''afTimeShown ''- time in seconds until the message disappears. If time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void BlockHint(string& asName);
void UnBlockHint(string& asName);
void RemoveHint(string& asName);
</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels.

"Removing" a hint actually removes it from the list of already given hints, thus allowing it to show up again.

''asName ''- the internal name. Basic game hints use the same name as their respective lang entries, with the exception of "numbered" hints. For example, <code>EntityGrab</code> blocks the <code>EntityGrab01</code> and <code>EntityGrab02</code> entries.

===Inventory===

<syntaxhighlight lang="c++">
void ExitInventory();
</syntaxhighlight>

Exits the inventory by force.

<syntaxhighlight lang="c++">
void SetInventoryDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open his inventory.

<syntaxhighlight lang="c++">
void SetInventoryMessage(string& asTextCategory, string& asTextEntry, float afTime);
</syntaxhighlight>

Adds a message at the bottom of the inventory screen.

''asTextCategory ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file ''afTime ''- time in seconds until the message disappears. If life time is <= 0 then the life time is calculated based on string length.

<syntaxhighlight lang="c++">
void GiveItem(string& asName, string& asType, string& asSubTypeName, string& asImageName, float afAmount);
</syntaxhighlight>

Adds an item to the inventory of the player. Note that the item does not have to exist as entity in the world to be able to do this.

''asName ''- internal name ''asType ''- item type to give, Available types are: 

*Puzzle
*Lantern
*Health
*Sanity
*LampOil
*Tinderbox

''asSubTypeName ''- item name for .lang file ''asImageName ''- the image which will appear in inventory. For example: <code>void GiveItem("chemical_container_full_1", "Puzzle", "chemical_container_full", "chemical_container_full.tga", 1);</code> will use the image from <code>graphics/item/chemical_container_full.tga</code>

''afAmount ''- amount the item gives, - For example: Oil potions will fill the oil meter by this amount, Health potions will heal by this amount, etc.

<syntaxhighlight lang="c++">
void RemoveItem(string& asName);
</syntaxhighlight>

Removes an item from the player's inventory.

<syntaxhighlight lang="c++">
bool HasItem(string& asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

<syntaxhighlight lang="c++">
void GiveItemFromFile(string& asName, string& asFileName);
</syntaxhighlight>

Adds a single item to the player's inventory. This is meant to be used for debug mostly as it creates the actual item and then destroys it.

''asName ''- internal name ''asFileName ''- item to give + extension (.ent)

<syntaxhighlight lang="c++">
void AddCombineCallback(string& asName, string& asItemA, string& asItemB, string& asFunction, bool abAutoRemove);
</syntaxhighlight>

Allows the player to combine items in his inventory. Callback syntax: <code>void MyFunc(string &in asItemA, string &in asItemB)</code>

''asName ''- internal name for the callback ''asItemA ''- internal name of first item ''asItemB ''- internal name of second item ''asFunction ''- the function to call ''abAutoRemove ''- determines whether the callback should be removed when the items are combined

<syntaxhighlight lang="c++">
void RemoveCombineCallback(string& asName);
</syntaxhighlight>

Removes a combine callback. ''asName'' - the internal name of the callback to be removed (as specified in AddCombineCallback)

<syntaxhighlight lang="c++">
void AddUseItemCallback(string& asName, string& asItem, string& asEntity, string& asFunction, bool abAutoDestroy);
</syntaxhighlight>

Allows the player to use items on the world. Callback syntax: <code>void MyFunc(string &in asItem, string &in asEntity)</code>

''asName ''- internal name ''asItem ''- internal name of the item ''asEntity ''- entity to be able to use the item on ''asFunction ''- function to call ''abAutoDestroy ''- determines whether the item is destroyed when used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string& asName);
</syntaxhighlight>

Removes an item callback.

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string& asName, bool abActive);
</syntaxhighlight>

Activates/deactivates an entity.

<syntaxhighlight lang="c">
void SetEntityVisible(string &in asName, bool abVisible);
</syntaxhighlight>

{{ReqVer|1.3}}

Activates/deactivates an entity's visual mesh. The collision body remains.

''asName'' - Name of the entity. ''abActive'' - Activate/deactivate mesh.

<syntaxhighlight lang="c">
bool GetEntityExists(string& asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string& asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

''asName ''- internal name ''asCrossHair ''- desired crosshair, can be: Default (uses default), Grab, Push, Ignite, Pick, LevelDoor, Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes(using for example ShowEnemyPlayerPosition).

''asEntityName ''- internal name ''asEntityFile ''- entity to be used extension .ent ''asAreaName ''- the area to create the entity at ''abFullGameSave ''- determines whether an entity "remembers" its state

<syntaxhighlight lang="c">
void ReplaceEntity(string &in asName, string &in asBodyName, string &in asNewEntityName, string &in asNewEntityFile, bool abFullGameSave);
</syntaxhighlight>

{{ReqVer|1.3}}

Removes an entity and places a new one in its place.

''asName'' - Name of the entity to replace. ''asBodyName'' - Name of the body of the entity to place the new entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''asNewEntityName'' - Name of the new entity. ''asNewEntityFile'' - Name of the new entity file. Extension .ent. ''abFullGameSave'' - Whether ALL properties of this entity should be saved throughout levels.

<syntaxhighlight lang="c++">
void PlaceEntityAtEntity(string &in asName, string &in asTargetEntity, string &in asTargetBodyName, bool abUseRotation);
</syntaxhighlight>

{{ReqVer|1.3}}

Places an entity at the position of another entity. Does not work for enemies, use TeleportEnemyToEntity instead.

''asName'' - Name of the entity to place. ''asTargetEntity'' - Name of the other entity to place the first entity at. ''asTargetBodyName'' - Name of the body of the entity to place the first entity at. If empty the first body is used (might be buggy, recommended to name a body anyway). ''abUseRotation'' - Whether the entity should be rotated like the target entity.

<syntaxhighlight lang="c">
void SetEntityPos(string &in asName, float afX, float afY, float afZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Moves an entity to a position in the level.

''asName'' - Name of the entity to move. ''afX'' - X co-ordinate position. ''afY'' - Y co-ordinate position. ''afZ'' - Z co-ordinate position.

<syntaxhighlight lang="c">
float GetEntityPosX(string &in asName);
float GetEntityPosY(string &in asName);
float GetEntityPosZ(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns an entity's position in the level on the specified axis.

''asName'' - Name of the entity.

<syntaxhighlight lang="c">
void SetEntityPlayerLookAtCallback(string& asName, string& asCallback, bool abRemoveWhenLookedAt);
</syntaxhighlight>

Calls a function when the player looks at a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code> alState: 1 = looking, -1 = not looking

''asName ''- internal name ''asCallback ''- function to call ''abRemoveWhenLookedAt ''- determines whether the callback should be removed when the player looked at the entity

<syntaxhighlight lang="c">
void SetEntityPlayerInteractCallback(string& asName, string& asCallback, bool abRemoveOnInteraction);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity)</code>

''asName ''- internal name ''asCallback ''- function to call ''abRemoveOnInteraction ''- determines whether the callback should be removed when the player interacts with the entity

<syntaxhighlight lang="c">
void SetEntityCallbackFunc(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when the player interacts with a certain entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in type)</code> Type depends on entity type and includes: "OnPickup", "Break", "OnIgnite", etc

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string& asName, string& asCallback);
</syntaxhighlight>

A callback called when ever the connection state changes (button being switched on, lever switched, etc). Callback syntax: <code>void Func(string &in asEntity, int alState)</code> alState: -1 = off, 0 = between, 1 = on

<syntaxhighlight lang="c">
void SetEntityInteractionDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string& asName);
</syntaxhighlight>

Breaks a joint. Do not use this on joints in SwingDoors, Levers, Wheels, etc. where the joint is part of an interaction. That will make the game crash.

<syntaxhighlight lang="c">
void AddEntityCollideCallback(string& asParentName, string& asChildName, string& asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entites collide. Callback syntax: <code>void MyFunc(string &in asParent, string &in asChild, int alState)</code> alState: 1 = enter, -1 = leave

''asParentName ''- internal name of main object ''asChildName ''- internal name of object that collides with main object (asterix (<nowiki>*</nowiki>) NOT supported!) ''asFunction ''- function to call ''abDeleteOnCollide ''- determines whether the callback after it was called ''alStates ''- 1 = only enter, -1 = only leave, 0 = both

<syntaxhighlight lang="c">
void RemoveEntityCollideCallback(string& asParentName, string& asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string& asEntityA, string& asEntityB);
</syntaxhighlight>

Checks whether two entites collide. This function does NOT support asterix (<nowiki>*</nowiki>) or "Player"!

<syntaxhighlight lang="c">
void SetBodyMass(string &in asName, float afMass);
</syntaxhighlight>

{{ReqVer|1.3}}

Sets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to set.

<syntaxhighlight lang="c">
float GetBodyMass(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gets the mass of an entity's body.

''asName'' - Name of the body of an entity. The body name of an entity is EntityName_BodyName. ''afMass'' - The mass to get.

====Props====

<syntaxhighlight lang="c">
void SetPropEffectActive(string& asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Can be used on coal to give it the black color it should have.

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string& asName, bool abActive, float afFadeTime);
</syntaxhighlight>

Activates/deactivates a prop.

''asName ''- internal name ''abActive ''- nothing to add ''afFadeTime ''- time in seconds until prop fully fades

<syntaxhighlight lang="c">
void SetPropStaticPhysics(string& asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string& asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string& asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string& asOffsetArea);
</syntaxhighlight>

Rotates the prop up to a set speed.

''asName ''- internal name ''afAcc ''- acceleration ''afGoalSpeed ''- desired speed ''afAxisX ''- rotation around X axis ''afAxisY ''- rotation around Y axis ''afAxisZ ''- rotation around Z axis ''abResetSpeed ''- determines whether the speed is resetted after goal speed is reached ''asOffsetArea ''- the area to rotate around, if empty, then the center of the body is used Note: The entity you want to rotate MUST be a "StaticObject" entity!

<syntaxhighlight lang="cpp">
void StopPropMovement(string& asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

a''sPropName''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

{{bug|''afRotZ '' is used for both the ZX rotation and the Z position of the attached prop. Unwanted rotation can be avoided by using: ''AddAttachedPropToProp(asPropName, asAttachName, asAttachFile, afPosX, afPosY, '''0''', afPosZ, '''90.0f''', afPosZ)''}}

{{bug|Attaching a breakable prop to a physically active prop, and then breaking the attached prop, will cause the game to crash, should the parent object be moved or reset.}}

<syntaxhighlight lang="cpp">
void AttachPropToProp(string& asPropName, string& asAttachName, string& asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

{{ReqVer|1.3}}

Attaches a prop to another prop. Fixed version of AddAttachedPropToProp.

''asPropName ''- the prop to attach another prop at ''asAttachName ''- internal name of the prop that gets attached ''asAttachFile ''- the prop that gets attached extension .ent ''afPosX ''- X position of the attach from the prop ''afPosY ''- Y position of the attach from the prop ''afPosZ ''- Z position of the attach from the prop ''afRotX ''- rotation around X axis of the attach ''afRotY ''- rotation around Y axis of the attach ''afRotZ ''- rotation around ZX axis of the attach Note: for the purposes of "AddEntityCollideCallback", attached props will not call the callback function if they collide with a "static_object" or a "StaticProp" entity type!

<syntaxhighlight lang="cpp">
void RemoveAttachedPropFromProp(string& asPropName, string& asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string& asName, float afHealth);
void AddPropHealth(string& asName, float afHealth);
float GetPropHealth(string& asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string& asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string& asProp, string& asAnimation, float afFadeTime, bool abLoop, string& asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function. Callback syntax: <code>void MyFunc(string &in asProp)</code>

''asProp ''- internal name of the prop ''asAnimation ''- animation to play ''afFadeTime ''- ? ''abLoop ''- determines whether the animation loops ''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddPropImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyForce(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
void AddBodyImpulse(string& asName, float afX, float afY, float afZ, string& asCoordSystem);
</syntaxhighlight>

These functions push objects. Note that rather high values are needed when applying ''forces'' (on the order of ~100 (weak) to ~10000 (strong)), but not impulses (values less than 10 can be appropriate). Forces are external influences, and will have different effect depending on the mass of the object they are being applied to; impulses disregard mass, and can cause objects to break, as if hit. A "Body" is a physics-related helper object, to which a force or an impulse can be applied. Entities can consist of several bodies, interconnected in various ways (you can create/examine bodies in the model editor).

''asName ''- the object to push; for bodies, use this format: "''entityName''_''bodyName''" ''afX ''- magnitude along the X-axis ''afY ''- magnitude along the Y-axis ''afZ ''- magnitude along the Z-axis ''asCoordSystem ''- determines which coordinate system is used, usually "world" All of these functions are ''additive'' - when called consecutively, for each call, the vectors defined by (afX, afY, afZ) will be added together, and a resultant force/impulse will be calculated ''before'' any physics simulation is applied to the target object.

====Connections====

<syntaxhighlight lang="cpp">
void InteractConnectPropWithRope(string& asName, string& asPropName, string& asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (ie. turn wheel to move rope).

''asName ''- connection name ''asPropName ''- name of prop ''asRopeName ''- name of rope ''abInteractOnly ''- ? ''afSpeedMul ''- speed multiplier of how quickly the rope moves ''afToMinSpeed ''- the slowest the rope will move when moving the prop ''afToMaxSpeed ''- the fastest the rope will move when moving the prop ''abInvert ''- whether to invert the direction the rope moves ''alStatesUsed ''- which states of the prop can interact with the rope?

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string& asName, string& asPropName, string& asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondance to prope "amount" and the moveobject open amount. It is best used for Wheel-door connections!

<syntaxhighlight lang="cpp">
void ConnectEntities(string& asName, string& asMainEntity, string& asConnectEntity, bool abInvertStateSent, int alStatesUsed, string& asCallbackFunc);
</syntaxhighlight>

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> State is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string& asName, bool abLit, bool abEffects);
</syntaxhighlight>

(Un)lits a lamp.

''asName ''- Name of the lamp ''abLit ''- Set true if you want the lamp to be lit, set to false if you want the lamp to be unlit ''abEffects ''- If you want to have the lamp fade in/out when it gets (un)lit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string& asName, bool abLocked, bool abEffects);
void SetSwingDoorClosed(string& asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Locks/closes a swing door.

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string& asName);
bool GetSwingDoorClosed(string& asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string& asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string& asName);
</syntaxhighlight>

Returns an integer depending on how far the door is opened. -1 = angle is close to 0°, 1 = angle is 70% or higher of max, 0 = inbetween -1 and 1.

<syntaxhighlight lang="cpp">
void SetLevelDoorLocked(string& asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string& asName, string& asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string& asName, string& asTextCat, string& asTextEntry);
</syntaxhighlight>

Displays a message when interacting with a locked level door.

''asName ''- internal name ''asTextCat ''- the category in the .lang file ''asTextEntry ''- the entry in the .lang file

<syntaxhighlight lang="cpp">
void SetMoveObjectState(string& asName, float afState);
</syntaxhighlight>

Moves an object to a certain state.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween (and above, for example, the bridge_metal_vert) are valid too!

<syntaxhighlight lang="cpp">
void SetMoveObjectStateExt(string& asName, float afState, float afAcc, float afMaxSpeed, float afSlowdownDist, bool abResetSpeed);
</syntaxhighlight>

Moves an object to a certain state, extended method.

''asName ''- internal name ''afState ''- state of the object, 0 = closed, 1 = open, values inbetween are valid too! ''afAcc ''- acceleration ''afMaxSpeed ''- maximum speed ''afSlowdownDist ''- Distance to the target state before decceleration occurs. ''abResetSpeed ''- Set to True if the prop's speed should be reset before performing the movement, else the prop will accelerate from it's current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string& asName, int alState);
void SetWheelStuckState(string& asName, int alState, bool abEffects);
void SetLeverStuckState(string& asName, int alState, bool abEffects);
</syntaxhighlight>

Makes a prop<nowiki>\</nowiki>wheel<nowiki>\</nowiki>lever stuck in a certain state.

''asName ''- internal name ''alState ''- 0 = not stuck, 1 = at max, -1 = at min ''abEffects ''- use effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string& asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

''asName ''- internal name ''afAngle ''- angle ''abAutoMove ''- determines whether the wheel should move on its own

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string& asName, bool abX);
void SetLeverInteractionDisablesStuck(string& asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string& asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string& asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string& asName, string& asCallback);
</syntaxhighlight>

Calls a function when state changes. Callback syntax: <code>void MyFunc(string &in asEntity, int alState)</code>

<syntaxhighlight lang="cpp">
void SetButtonSwitchedOn(string& asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entites to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string& asAreaName, string& asProp);
void AttachBodyToStickyArea(string& asAreaName, string& asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string& asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====Enemies====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string& asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Activates the npc

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string& asName, bool abX);
</syntaxhighlight>

Sets an NPC's head to follow the player's movement's.

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string& asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string& asName, bool abX);
</syntaxhighlight>

Makes an enemy a hallucination. Hallucinations fade to smoke when they get near the player.

<syntaxhighlight lang="cpp">
void FadeEnemyToSmoke(string& asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string& asName);
</syntaxhighlight>

Makes the enemy run to the player, no matter where he is.

<syntaxhighlight lang="cpp">
void AlertEnemyOfPlayerPresence(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Gives the specified enemy the player's current position and makes it search the area.

<syntaxhighlight lang="cpp">
void SetEnemyDisableTriggers(string& asName, bool abX);
</syntaxhighlight>

Enables or disables enemy triggers. If disabled, enemy will not react to player or attack.

<syntaxhighlight lang="cpp">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation);
</syntaxhighlight>

Adds a patrol node to the enemy's path.

''asName ''- internal name of the enemy ''asNodeName ''- path node ''afWaitTime ''- time in seconds that the enemy waits at the path node before continuing ''asAnimation ''- the animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string& asEnemyName);
</syntaxhighlight>

Clears the current path of patrol nodes of the enemy.

<syntaxhighlight lang="cpp">
void SetEnemySanityDecreaseActive(string &in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether an enemy activates the player's sanity drain when stared at.

''asName ''- Internal name of the enemy ''abX ''- Enabled/disabled

<syntaxhighlight lang="cpp">
void TeleportEnemyToNode(string &in asEnemyName, string &in asNodeName, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific PathNode.

''asEnemyName ''- Internal name of the enemy ''asNodeName ''- Internal name of the node to teleport to ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="cpp">
void TeleportEnemyToEntity(string &in asEnemyName, string &in asTargetEntity, string &in asTargetBody, bool abChangeY);
</syntaxhighlight>

{{ReqVer|1.3}}

Teleports an enemy to a specific entity.

''asEnemyName ''- Internal name of the enemy ''asTargetEntity ''- Internal name of the entity to teleport to ''asTargetBody''- Internal name of the entity's body name to teleport to. If empty, the first body will be used (might be unstable, recommended to input a body anyway) ''abChangeY ''- Whether the Y position of the node will be used when teleporting the enemy

<syntaxhighlight lang="c">
void ChangeManPigPose(string&in asName, string&in asPoseType);
</syntaxhighlight>

{{ReqVer|1.3}}

Changes the pose a specified ManPig.

''asName ''- Internal name of the enemy ''asPoseType''- Name of the ManPig pose to use. Can be "Biped" or "Quadruped"

<syntaxhighlight lang="c">
void SetTeslaPigFadeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should fade the player's view in and out.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should play the proximity sounds.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string&in asName, bool abX);
</syntaxhighlight>

{{ReqVer|1.3}}

Enables/disables whether a specified TeslaPig should be easier to escape from when hunted.

''asName ''- Internal name of the enemy ''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string&in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a TeslaPig to be visible for a short time.

''asName ''- Internal name of the enemy

<syntaxhighlight lang="c">
string& GetEnemyStateName(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Returns the name of the state a specified enemy is current in. States can be Hunt, Search, Patrol, Wait, Alert, Investigate, Track and BreakDoor.

''asName ''- Internal name of the enemy

HPL2/Tutorials

2024-01-04T16:58:59Z

Mrbehemo: Added link to ShowScreenImage()

=Text tutorials=

This page lists a large amount of tutorials, most of which are community-made. Feel free to check them out and see if they can teach you something. If you've made a tutorial and wish to add it to this page, you can do so by editing it to the right. Just try to keep to the same format as the rest of the page.

{{tip|If you can't find a tutorial for what you need, make sure to check the [[HPL2/Tools#Editors|Editor documentation]] and [[HPL2/TDD#Documentation|Engine documentation]]. An example of this would be the Particle Editor.}}

==Level Editor==

* [[:hpl2:tutorials:level_editor:tutorial_1|Tutorial 1]] - The minimum required to get a level that can load.
* [[:hpl2:tutorials:level_editor:tutorial_2|Tutorial 2]] - Placement of lights and advanced setup of lights.
* [[:hpl2:tutorials:level_editor:tutorial_3|Tutorial 3]] - How to make an outdoor environment. There's a [[Hpl2:Tutorials:level_editor:outdoors|newer version of i]]t available.
* [[:hpl2:tutorials:level_editor:tutorial_4|Tutorial 4]] - Explains how to make water.
* [[:hpl2:tutorials:level_editor:tutorial_5|Tutorial 5]] - Prop dimensions and detailing your map.
*[[Hpl2:Tutorials:level editor:tutorial 6|Tutorial 6]] - ???????
*[[HPL2/Tutorials/Skyboxes|Tutorial 7]] - Making skyboxes for HPL2
*[[HPL2/Tutorials/Level Design]] - Using all of the basic techniques to achieve good effects
* [[:hpl2:tutorials:level_editor:level_editor_101|Level Editor 101]] - All the basics and some more advanced techniques.

==Model Editor==

* [[:hpl2:tutorials:model_editor:tutorial_1|Basic tutorial]] - The minimum required to load a model as an entity with collision and game properties.
* [[:hpl2:tutorials:model_editor:tutorial_2|Creating Ragdoll Entities]] - How to create full physics-based entities.
* [[:hpl2:tutorials:model_editor:static_objects_jenniferorange|Making Items Static]] - How to change an items' properties to static.
* [[HPL2/Tutorials/Coin_chests | Coin chests]] - How to create chests that can be only opened with coins.

==Material Editor==

* [[:hpl2:tutorials:material_editor:tutorial_1|Tutorial 1]] - Basic materials and their properties.
* [[Hpl2:Tutorials:material editor:creating mirrors|Creating mirrors]] - make reflective surfaces using water materials

==Game files==
* [[:hpl2:tutorials:script:CustomSounds|How to create Custom Sounds]] - Teaches how to create custom sounds for your custom story.
* [[:hpl2:tutorials:script:howtomakenotes|How to Create Notes and Journal Entries]] - Explains how to make journal entries and place them in a map
* [[HPL2/Tutorials/Porting MFP Assets|Porting MFP Assets]] - explains how to copy assets from MFP to TDD and avoid issues
* [[HPL2/Tutorials/Convert HDRI to skyboxes|Convert HDRI to skyboxes]]

==Scripting tutorials==
General basics:

*[[HPL2/Tutorials/Scripts/Debugging|Make your set-up comfortable for scripting]]
* [[:hpl2:tutorials:script:entihscript_beginner|Newbie's Guide to Scripting]] - A tutorial for those new to scripting, focusing on syntax and a few helpful hints - ''By 'Entih''
* [[:hpl2:tutorials:script:tutorial_1|Tutorial 1]] - Using a tutorial level, with some objects to make basic scripts.
* [[:hpl2:tutorials:scripting:messages_jenniferorange|Activating/Using Message Pop-Ups]] - Explains how to activate a message to appear when walking into a script area.
* [[:hpl2:tutorials:scripting:triggering_monsters_on_entities|Triggering monsters on entities]] - Explains how to trigger an event after picking up an item.

Door-related script tutorials:

* [[:hpl2:tutorials:script:scripting_by_xtron_-_item_that_unlocks_a_door|Item That Unlocks a Door]] - How to make an item that unlocks a certain door.
* [[:hpl2:tutorials:script:buttons_that_open_a_door|Buttons that open door]]s - Explains how to make buttons that open doors.
* [[:hpl2:tutorials:script:events|Scary door events]] - Explains how to make scary door events.
* [[:hpl2:tutorials:scripting:crowbartutorialjenniferorange|Using A Crowbar On A Door]] - Explains how to script a crowbar to blow open a door.
* [[:hpl2:tutorials:script:adding_messages_to_locked_doors|Adding Messages To Locked Doors]] - Explains how to display a message when a player tries to open a locked door.

Useful coding practices:

* [[:hpl2:tutorials:script:forloop|The "For" loop]] - Explains how and when to use the "for" loop.
* [[:hpl2:tutorials:script:advancedtimers|Advanced Timers]] - Explains how to use multiple timers in one function.
* [[:hpl2:tutorials:script:localandglobalvariables|Local and Global Variables]] - Explains what they are and how to use them correctly.
* [[:hpl2:tutorials:script:sequences|Scripting Sequences]] - Explains how to build simple and easy to use cutscenes, or sequences for your mod.

Forces and impulses:

* [[:hpl2:tutorials:script:force|Impulse and forces]] - Explains how to use force and impulse.
* [[:hpl2:tutorials:script:pushdoorsopen|Push doors open using force]] - Explains how to use Force to open doors and entities.
* [[Hpl2:Tutorials:level_editor:dynamic_curtains|Dynamic curtains]] - Using force to simulate wind
* [[:hpl2:tutorials:script:disable_gravity_tutorial|"Disable" gravity and make objects float]] - Make entities seem to float using timer functions and forces

Other:

* [[:hpl2:tutorials:script:monsterpathnodes|Monster Path Nodes]] - Explains how to set up a monster's path and how to trigger it.
* [[:hpl2:tutorials:script:levers_and_secretshelfs|Levers and secret bookshelves]] - Explains how to make a lever that opens a bookshelf.
* [[:hpl2:tutorials:scripting:scaresbyjenniferorange|Scares]] - Explains in as much detail as possible the multiple scares you can use without having to bring out the monsters.
* [[:hpl2:tutorials:level_editor:combininghammerchipperjenniferorange|Combining The Hammer And Chipper]] - Explains how to combine your hammer and chipper in your inventory.
* [[:hpl2:tutorials:scripting:checkpoints_using_scriptarea_s|Checkpoints using Areas]] - Explains how to make a checkpoint using Areas.
* [[:hpl2:tutorials:script:tutorialsformainmenu|How to create your own Main Menu Backgrounds!]] - The usability of Amnesia's .cfg files and its Editors
* [[HPL2/Tutorials/ShowScreenImage()|ShowScreenImage()]] - Some notes about the ShowScreenImage() function new to ATTD in version 1.5 (and also AAMFP).

==Modeling==

* [[:hpl2:tutorials:modeling:tutorialoutsource|Modeling tutorial]] - Initially written for outsourcers.

=Video tutorials=
Sublists:
*[https://www.youtube.com/playlist?list=PLIYfl4qBRihBjRpmQL-izQ4xdAtLblU36 Large playlist of video tutorials for beginners and intermediate developers] - ''By Mudbill''
*[[Hpl2:Tutorials:script:elventutorials|Elven's tutorials]]

==By Simpanra==
* [http://www.youtube.com/watch?v=CklTIT2W4g4 How To Make Level Door]
* [http://www.youtube.com/watch?v=ABI7NUqkXW0 How To Get a Key To Unlock a Door]
* [http://www.youtube.com/watch?v=v4WudNebX08 How To Make Water]
* [http://www.youtube.com/watch?v=ESISPLDbMWM How To Make a Custom Story Background]
* [http://www.youtube.com/watch?v=RmIKTH9YRqk How To Make a Functional and Interactable Ladder]
* [http://www.youtube.com/watch?v=riFwThqQ68k How To Name and Describe Keys]
* [http://www.youtube.com/watch?v=M5x_taEkP8s Simple Script Function]
==By Khyrpa==
* [http://www.youtube.com/watch?v=1R2F2eVmJ5k Building and Lighting in The Level Editor]
* [http://www.youtube.com/watch?v=d2ShkLEgGNk Lighting in Level Editor]
* [http://www.youtube.com/watch?v=u8EhP59tmjA Billboards]
* [http://www.youtube.com/watch?v=LKxzoAIK8jA Advanced Candle Light Connecting]
* [http://www.youtube.com/watch?v=xIDCoEZ581Q Wind Scare (Part 1)]
* [http://www.youtube.com/watch?v=Kj-NFkIGafI Wind Scare (Part 2)]
==By MulleDK19==
* [http://amnesia.treesoft.dk/tutorials/Tutorial1.wmv Make a key unlock a specific door]
* [http://amnesia.treesoft.dk/tutorials/Tutorial2.wmv How to create and use Areas or Triggers]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial1.wmv Using the Level Editor (Part 1)]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial2.wmv Using the Level Editor (Part 2)]
* [http://amnesia.treesoft.dk/tutorials/EditorTutorial3.wmv Using the Level Editor (Part 3)]
==By others==
* [http://www.youtube.com/watch?v=0grr7uipnk0 How To Create a Custom Story] - ''By TheVegaNVega''
* [http://www.youtube.com/watch?v=uGCTwQQSZ0A How To Make Journal Entries/Notes] - ''By RussMoney''
* [http://www.youtube.com/watch?v=WfgFEG4TSCE How To Make Journal Entries/Mementos] - ''By RussMoney''
* [http://www.youtube.com/watch?v=puIfVx0lslA How To Convert a Custom Story To a Full Conversion] - ''By RussMoney''
* [http://www.youtube.com/watch?v=9uKBYVEyw1s How to convert cube map images to DDS format in the GIMP] - ''By YourComputer''
* [http://www.youtube.com/playlist?list=PLD326789BC99530C8 From Noob to Pro: Amnesia Custom Story Creation Series] - ''By YourComputer''
* [http://www.youtube.com/watch?v=EnCAbgTY6d8 Adding Voice to your Diaries] - ''By triadtimes''
* [http://www.youtube.com/watch?v=vQEdIAZw5gM&feature=plcp&context=C4347014VDvjVQa1PpcFNKLAyG_d-p_QR49e20E_Wo08wpqmVkJz0= How to create a custom main menu background] - ''By CTCommunity''
* [http://youtu.be/Crx5Qd7AgJ0 Using Prop Force: How Do I Know Which Coordinate To Put My Value In?] - ''By JenniferOrange''

HPL2/Tutorials/ShowScreenImage()

2024-01-04T16:54:32Z

Mrbehemo: Added examples and conclusion.

=Introduction=
ATDD version 1.5 added the ShowScreenImage() function, which was previously available in AAMFP. Some of the workings of this function are a little counter-intuitive, so the purpose of this page is to explain it a little. This is based off of the author's experiments in ATDD 1.5, so it's not definitive! It's also assumed that these notes apply to AAMFP in the same way, but that has not been tested.

=Function=
<syntaxhighlight lang="c++">
void ShowScreenImage(string &in asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</syntaxhighlight>

Displays an image file directly onto the screen.

# ''asImageName'' - The image file to render (.jpg, .png, .tga, .dds) (see Size)
# ''afX'' - The X position of the image (see Placement)
# ''afY'' - The Y position of the image (see Placement)
# ''afScale'' - The size of the image in pixels (see Size)
# ''abUseRelativeCoordinates'' - If true, X and Y represent a fraction of the entire screen resoltion, otherwise they are pixel co-ordinates (see Placement)
# ''afDuration'' - The duration, in seconds, that the image is displayed for (see Timing)
# ''afFadeIn'' - The time, in seconds, to fade in the image (see Timing)
# ''afFadeOut'' - The time, in seconds, to fade out the image (see Timing)

=Size=
* Note that the ''afScale'' argument is ''not'' actually the scale of the image: it is the ''size in pixels''. This is not relative and does not take the screen resolution into account, so an image will appear bigger or smaller at lower or higher resolutions respectively.
* The image will be rendered onscreen as a square quad, even if the image file is non square. So if the desired effect is to display a non-square image, it will need to be padded out with transparent pixels in order to make it render without distortion.

=Placement=
* The origin of the screen-space is the centre. This means that [0, 0] is the centre of the screen regardless of screen resolution, and regardless of ''abUseRelativeCoordinates''.
* The origin of the image-space is the top-left. This means that the co-ordinates define where the top-left corner of the image will go.
* If ''abUseRelativeCoordinates'' is ''false'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as actual pixels''.
* If ''abUseRelativeCoordinates'' is ''true'', then X and Y represent the co-ordinates of the top-left corner of the image, relative to the centre of the screen, ''expressed as a fraction of the screen resolution width or height''.
* The relative co-ordinates still use the centre of the screen as the origin, so the top-left corner of the screen is [-0.5, -0.5] and the bottom-right corner is [0.5, 0.5]. Any relative co-ordinate greater than 0.5 will put the image outside of the screen.

=Timing=
* The total time that the image will be displayed is ''afFadeIn'' + ''afDuration'' + ''afFadeOut''.
* ''afDuration'' counts from when the fade in is finished. ''afFadeOut'' counts from when ''afDuration'' is finished.
* Calling ShowScreenImage() again will replace the current image, regardless of duration or fade times.

=Examples=
<syntaxhighlight lang="c++">
// Centred:
ShowScreenImage("image.dds", -150.0f, -150.0f, 300.0f, false, 3.0f, 0.0f, 0.0f);
// Size: 300 x 300 pixels
// Placement: centred on the screen (image-origin is placed image-size/2 from the screen-origin)
// Timing: 3 seconds, no fading

// From top-left:
ShowScreenImage("image.dds", -0.45f, -0.45f, 100.0f, true, 2.0f, 1.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-left corner, with a 5% margin relative to the screen size
// Timing: 5 seconds, including fading

// From top-centre:
ShowScreenImage("image.dds", -0.48f, 0.0f, 100.0f, true, 0.0f, 2.0f, 2.0f);
// Size: 100 x 100 pixels
// Placement: near the top-centre, with a 2% margin relative to the screen size
// Timing: 4 seconds, fading out immediately after fading in

// Bottom-right - not reliable
ShowScreenImage("image.dds", 0.25f, 0.25f, 270.0f, true, 1.0f, 1.0f, 1.0f);
// With a screen resolution of 1920 x 1080, this would fit neatly into the bottom-right 1/16 of the screen (1080 / 4 = 270).
// Unfortunately, if the resolution was lower, it would not fit on the screen. And if the resolution was higher, it would not reach the edges.

// Full-screen kinda... top-left focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would be at the centre of the screen at 4k, but would move towards the bottom left with lower resolutions.
// At lower resolutions the right and bottom of the image would be cropped. At higher resolutions it would not fill the screen.

// Full-screen kinda... centre focussed
ShowScreenImage("image.dds", -0.5f, -0.5f, 3840.0f, true, 1.0f, 1.0f, 1.0f);
// With a 4k screen resolution of 3840 x 2160, this would fit the full screen.
// The centre of the image would stay on the centre of the screen, whatever the resolution.
// At lower resolutions all the edges would be cropped. At higher resolutions it would not fill the screen.
</syntaxhighlight>

=Conclusion=
There are lots of things you can do with ShowScreenImage() if you use it creatively...

If you need to place an image relative the the right-hand edge or bottom of the screen, or relative to the screen resolution, it might be tricky, and might not be future-proof.

HPL2/Tutorials/ShowScreenImage()

2024-01-04T15:05:26Z

Mrbehemo: Mrbehemo moved page ShowScreenImage() to HPL2/Tutorials/ShowScreenImage()

ShowScreenImage()

2024-01-04T15:05:26Z

Mrbehemo: Mrbehemo moved page ShowScreenImage() to HPL2/Tutorials/ShowScreenImage()

#REDIRECT [[HPL2/Tutorials/ShowScreenImage()]]

HPL2/Tutorials/ShowScreenImage()

2024-01-04T15:04:41Z

Mrbehemo: Notes about using the ShowScreenImage() function in ATTD 1.5 and AAMFP.

HPL2/HPL2 Helper Scripts

2023-12-24T14:12:10Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''Lots of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2023-12-24T14:11:51Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''''The majority of help, and full details of the new classes and functions, can be found on the following pages:'''''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

__FORCETOC__

HPL2/HPL2 Helper Scripts

2023-12-24T14:11:29Z

Mrbehemo:

{{TocRight}}
=Introduction=
''HPL2 Helper Scripts'' by Aetheric Games is a package of .hps files containing script classes and functions that may be useful to HPL2 modders and custom story creators. It is compatible with ATDD version 1.5 and later.

Would you like to...
<blockquote>
...make 500 candles blow out in a big wave? ...make haunted objects hover in the air? ...spawn dozens of random debris objects throughout an area? ...make a particle system move along a spline? ...manage a list of quest objectives? ...compare the distances between entities? ...make puzzles based on position and rotation? ...store an array in a global game variable? ...seamlessly teleport the player into an ''almost'' identical room? ...make a statue that twitches when the player has low sanity?
</blockquote>
Well, this script package isn't going to magically do those things for you, but it gives you a ''lot'' of tools to help you do them yourself.

The scripts are divided into two categories: ''utilities'' and ''features''. The ''utilities'' scripts include tools for general scripting, like new maths functions, or linked lists and vector classes. The ''features'' scripts are more specific solutions that make use of the utilities, such as a way to spawn entities at specific locations, script a large chain of events or to make entities twitch and flicker. Some modders might prefer to just adopt the ''utilities'' scripts. It's up to you!

<big>'''[[HPL2/HPL2 Helper Scripts#Set-up|See below for download and set-up instructions.]]'''</big>

=Contents=
The documentation and help is organised by file. '''The majority of help, and full details of the new classes and functions, can be found on the following pages:'''
{|
|-
|
==Utilities==
:* [[HPL2/HPL2 Helper Scripts/Debug|<big><big>'''Debug'''</big></big>]]
::Provides more control and options for debug messages and logging.
:* [[HPL2/HPL2 Helper Scripts/GameVars|<big><big>'''GameVars'''</big></big>]]
::Extends the functionality of the saved game global and local variable wrappers.
:* [[HPL2/HPL2 Helper Scripts/Lists|<big><big>'''Lists'''</big></big>]]
::Adds support for linked list classes.
:* [[HPL2/HPL2 Helper Scripts/LoadWatcher|<big><big>'''LoadWatcher'''</big></big>]]
::Provides an "OnLoad()" global function.
:* [[HPL2/HPL2 Helper Scripts/Math|<big><big>'''Math'''</big></big>]]
::Provides extended maths functionality.
:* [[HPL2/HPL2 Helper Scripts/String|<big><big>'''String'''</big></big>]]
::Provides extended string functionality.
:* [[HPL2/HPL2 Helper Scripts/Vectors|<big><big>'''Vectors'''</big></big>]]
::Adds support for vector classes.
||          ||
==Features==
:* [[HPL2/HPL2 Helper Scripts/Bobber|<big><big>'''Bobber'''</big></big>]]
::Implements a class for floating or hovering entities, without physics.
:* [[HPL2/HPL2 Helper Scripts/Fader|<big><big>'''Fader'''</big></big>]]
::Implements a class for managing global ambient sounds.
:* [[HPL2/HPL2 Helper Scripts/Glitcher|<big><big>'''Glitcher'''</big></big>]]
::Implements a class for managing entities that appear to glitch or flicker.
:* [[HPL2/HPL2 Helper Scripts/Slimer|<big><big>'''Slimer'''</big></big>]]
::Implements a class for managing large sequences of entity actions.
:* [[HPL2/HPL2 Helper Scripts/Spawner|<big><big>'''Spawner'''</big></big>]]
::Implements a class for spawning entities at specific map locations.
:<big><big> </big></big>
:: 
:* [[HPL2/HPL2 Helper Scripts/Misc|<big><big>'''Miscellaneous'''</big></big>]]
::Bits and pieces that don't fit anywhere else.
|}

=Set-up=
 
{{ReqVer|1.5}} 
 
First, download ''HPL2 Helper Scripts'' from the [https://steamcommunity.com/sharedfiles/filedetails/?id=3101276708 Steam Workshop page] or [https://www.moddb.com/mods/hpl2-helper-scripts ModDb page] and unzip it.

If you get it on Steam Workshop, you'll find the actual folder in your Steam Workshop downloads.

Once you have zipped the folder, there are three options for how you add it into your mod. '''If you are unsure, just go with option A'''. 

===Option A: The full feature-set package===
::If you want to be able to use all the new functions and classes, go with option A.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_FullPackage.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_FullPackage.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option B: The utilities-only package===
::Choose option B if you want to have access to the functions and classes in the ''utilities'' category, but don't need the stuff in the ''features'' category.
::#Copy the folder <code>HPL2HelperScripts</code> into your <code>maps</code> folder.
::#Include <code>HelperScripts_UtilitiesOnly.hps</code> in your level's <code>.hps</code> script file using the <code>#include</code> directive.
::#Add <code>HelperScriptsUpdate(afStep)</code> to your main <code>OnUpdate()</code> function in your level's <code>.hps</code> script file.
::For example, in <code>myLevel.hps</code>:
::<syntaxhighlight lang="cpp">
#include "HelperScripts_UtilitiesOnly.hps"

void OnUpdate(float afStep)
{
HelperScriptsUpdate(afStep);
}
</syntaxhighlight>

===Option C: Pick-n-mix===
::Advanced modders might prefer to only adopt the specific script files they need. Go nuts! But also be aware of the #include dependencies in each script file, as many of them are interdependent. You might find it easiest to start with option A or B and then remove scripts later that you definitely haven't used. You're also fully allowed and encouraged to just use HPL2HelperScripts as a learning resource or even to just copy snippets here and there.

=Licence and Credits=
You are free to use ''HPL2 Helper Scripts'' in whatever way you see fit, no rights reserved by Aetheric Games. (As long as you're not going against any licence terms between you and Frictional Games, of course!) Aetheric Games is mostly just one person, mrbehemo, me (hello), and this has been a ''stupid'' amount of work, so if you find it helpful then it would be very cool of you to give me a credit in your mod or custom story. You can list it as "HPL2 Helper Scripts by Aetheric Games".

This script package would not have been possible without the work of the tireless and patient Luis Rodero of Frictional Games, and the ever present pillar of the community, Mudbill.

=Support=
''HPL2 Helper Scripts'' is made by mrbehemo of Aetheric Games. If you need support, here's what to do:
#First be sure that you're familar with the official [[HPL2/Engine_Scripts|HPL2 scripting reference]] and the [[HPL2/ScriptReference|community scripting guide]].
#And second, be sure that you've read the relevant parts of this documentation, including the FAQ.
#And then if you're still stuck I'll be happy to hear from you and will help if I can. Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server].

=FAQ=
Fervently Anticipated Questions. Nobody's asked anything yet...
* I've added one or more scripts to my project separately, but I'm getting errors. What should I check?
** The script files are very interdependent. Check the .hps files you've added - they will have #include directives near the top for every other script they rely on. Either make sure you've also added ''those'' into your project.
* What's "#include"? What's "OnUpdate()"?
** Those are new features added with the ATDD [[HPL2/1.5 Update|1.5 update]].
* I want to make something weird happen, like make 100 flying naked guys do a loop-de-loop around the player. How?
** Sounds fun and is probably do-able! Come and find me on [https://discord.com/invite/frictionalgames the Frictional Discord server] if you want advice.
* Can I get the player's camera direction yet?
** No, sorry. I investigated multiple ways of doing that, as have many people over the years. There's just no reliable way of doing it in HPL2 without branching the source code.
* What's a uint and why have you used them everywhere?
** A "U-int" is an unsigned integer, that is, an integer that can only be positive. I think it's best to use uint in scenarios where negative numbers are nonsensical. Behind the scenes it minimises the the chance of conversion issues, and also minimises warnings in the error output.
* Why are all your function arguments passed by reference, and why is that not reflected in the docs?
** In Angelscript there's a tiny, tiny performance saving gained from passing arguments by reference (and by using const where possible). It's not enough of a saving for modders and gameplay scripters to bother with, but since I was writing hundreds of them, it was an easy thing to do. It's not reflected in the docs because most non-advanced modders don't know what "pass by reference" means, or need to know.
* I looked at your code and you did it all weird. Why did you do it weird?
** It's probably because of the version of Angelscript that is integrated into HPL2. It has some surprising versatility but also some surprising limitations.
* Why did you do any of this?
** I know, I know - HPL2 is old now, I should have done this for The Bunker or whatever. Actually, I was just tidying up The Trapdoor (ATDD mod) for a Steam release, and I got carried away with refactoring it... and then, half a million characters of script later, this had happened. Hope it's useful. If not, it was a good exercise for me. Maybe ''you'' would like to port these scripts to HPL3 as and where needed! Go ahead, just be sure to credit and it'd be cool to let me know.

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2023-12-23T19:04:59Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.

There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem)
bool Set(uint aulIndex, float afItem)
bool Set(uint aulIndex, double adItem)
bool Set(uint aulIndex, bool abItem)
bool Set(uint aulIndex, string asItem)
bool Set(uint aulIndex, cVector avItem)
bool Set(uint aulIndex, cPoint avItem)
bool Set(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Assigns a new value to an indexed item in the list, if it exists. If the list is shorter than the index or the item cannot be added, this returns false. If it was successfull set, it returns true.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
<syntaxhighlight lang="cpp">
// Example:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Arrays from lists===
cListBase and its derived classes provide the following methods for transforming lists into arrays:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes an new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToArray()
</syntaxhighlight>
Makes an new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

HPL2/HPL2 Helper Scripts/Lists

2023-12-23T18:57:06Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Lists.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types.

A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name. The advantages to using lists over arrays is that it is programmatically easier (and more performant) to insert, remove or re-order items in the list than it would be with an array.

Lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. It is not necessary to know in advance how big a list needs to be - it expands automatically as items are added.

===The basics===
Declare a list like any other variable, then use the methods below to work with it. For example:
<syntaxhighlight lang="cpp">
cListInt myList; // Declares a new cListInt, called myList, ready to collect integers.
myList.Add(68); // Appends the first integer (68) to the list at index 0.
myList.Add(419); // Appends the second integer (419) to the list at index 1.
myList.Get(0); // Retrieves the integer at index 0.
myList.Set(1, 99); // Overwrites the integer at index 1.
</syntaxhighlight>

===Indices===
Like arrays, you can ''get'' the items in the list using an index operator, e.g. myList[0], myList[22], myList[LastIndex]. And like arrays, the index number is '''zero based'''. In a list or array of ten items, the first index is 0 and the last index is 9.

Getting an item from a list by its index is equivalent to using the Get() method. However, ''unlike arrays'', this is '''read-only'''. For example:
<syntaxhighlight lang="cpp">
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0); // OK
string myStringOne = myToDoList[1]; // OK

myToDoList.Set(0, "Paint over the lines."); // OK
myToDoList[1] = "Cut the cheese."; // Not OK
</syntaxhighlight>

(This seems to be because the version of AngelScript used in HPL2 seems to only allow the index operator to ''get'' and not ''set''. If I'm wrong and you can make this work, let me know!)

===Advanced info===
"HelperScripts_Lists.hps" also defines cListNodeBase and several derived node classes for each type of list. The list classes all inherit from the base class cListBase, which defines some shared functionality and handles anything that doesn't depend on the type of the stored data.

Additionally, cListGeneric is an extra list class intended for advanced users. It extends the cListBase class without defining an inner data type, to help with making custom node classes derived from cListNodeBase. Advanced users attempting this may find it helpful to take a look at the cListBase and cListGeneric definition, and to read up on how AngelScript uses object handles. Examples can be found in most of the ''features'' scripts, e.g. "HelperScripts_Slimer.hps", which implements multiple custom node classes and nested lists.

=List classes=

Available list classes: <code>cListInt</code>, <code>cListFloat</code>, <code>cListDouble</code>, <code>cListBool</code>, <code>cListString</code>, <code>cListVector</code>, <code>cListPoint</code>, <code>cListRotator</code>

The "List classes" section refers to all the list types unless otherwise stated.

==Behaviours==
Lists can be declared in the same way as other variables:
<syntaxhighlight lang="cpp">
cListFloat listOfFloats; // Declares a list of floats.
cListString listOfStrings; // Declares a list of strings.

myListOfFloats.Add(0.001f); // Calling a method of the referred list.
int numStrings = myListOfStrings.Count; // Accessing a property of the referred list.
</syntaxhighlight>

===Constructor with capacity===
<syntaxhighlight lang="cpp">
cListBase(uint aulMaxSize)
</syntaxhighlight>
If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
 If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).

<syntaxhighlight lang="cpp">
// Example:
cListFloat listOfFloatsDefault;
cListVector listOfVectorsDefault;

cListFloat listOfUpToFiveFloats = cListFloat(5);
cListVector listOfUpTo1000Vectors = cListVector(1000);
</syntaxhighlight>

The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.

===Constructor with data===
<syntaxhighlight lang="cpp">
cListBase(float[] afArray)
cListBase(cListBase aList)
</syntaxhighlight>
Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 If the source is an array, the new list will contain copies of the array's contents. If the source is an existing list, then the new list will copy the ''link'' to the original items. Both the old and new lists will point to the same data, and changing one will change the other. To avoid this, see the [[HPL2/HPL2_Helper_Scripts/Lists#Copy.28.29|Copy()]] method.
<syntaxhighlight lang="cpp">
// Example:
float[] myArray = { 4, 8, 15, 16, 23, 42 };
cListFloat myFirstList = cListFloat(myArray); // Makes a new float list by copying items from the float array.
cListFloat mySecondList = myFirstList; // Makes a new float list containing the same items as the other list.
</syntaxhighlight>
 
<syntaxhighlight lang="cpp">
cListFloat(float afSingleFloat)
</syntaxhighlight>
All the derived list classes ('''except for cListGeneric and cListInt''') can be initialised with data by passing a single value of the relevant type, to become the first item in the list.
<syntaxhighlight lang="cpp">
// Example:
cListFloat myList = cListFloat(1.2f); // Makes a new float list with a single value.
myList.Add(2.3f); // myList now contains: 1.2f, 2.3f
</syntaxhighlight>

==Properties==
'''All list classes''' provide the following properties:

====Count====
<syntaxhighlight lang="cpp">
uint Count
</syntaxhighlight>
The read-only integer property Count returns the current number of items in the list.
(The property Length and the method length() are provided for consistency with arrays, and are both equivalent to Count.)
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat myList;
uint ulCountA = myList.Count;
myList.Add(99.99f);
uint ulCountB = myList.Count;
// ulCountA is 0. ulCountB is 1.

// Example 2:
if (listNumbers.Count < 6) listNumber.Add(42);
// The condition succeeds if the count is less than 6, and another number is added.
</syntaxhighlight>

====LastIndex====
<syntaxhighlight lang="cpp">
uint LastIndex
</syntaxhighlight>
The read-only integer property LastIndex returns the last valid index, or -1 if the list is empty.
<syntaxhighlight lang="cpp">
// Example 1:
uint ulA = myListOfStrings.LastIndex;
uint ulB = myListOfStrings.Count - 1;
// ulA and ulB are equal

// Example 2:
string sLatest = myListOfStrings[myListOfStrings.LastIndex];
// sLatest becomes whatever string was added to the list most recently.
</syntaxhighlight>

====IsEmpty====
<syntaxhighlight lang="cpp">
bool IsEmpty
</syntaxhighlight>
The read-only boolean property IsEmpty returns true if the list is empty, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (myList.IsEmpty) myList.Add(1);
// The condition succeeds if the list contains no items.
</syntaxhighlight>

====IsFull====
<syntaxhighlight lang="cpp">
bool IsFull
</syntaxhighlight>
The read-only boolean property IsFull returns true if the list is full to its maximum capacity, or false if not.
<syntaxhighlight lang="cpp">
// Example:
if (!myList.IsFull) myList.Add(1);
// The condition succeeds if the list has space for another item.
</syntaxhighlight>

==Operators==

====Assignment====
<syntaxhighlight lang="cpp">
cListBase = cListBase
</syntaxhighlight>
The assignment operator (equals sign "=") assigns a new set of data to the list, copied from another list. Note: the list contains handles to the data, not the data itself. So when a list is copied, ''both'' lists now refer to the same data, and any changes made to either will affect both.
 If the intent is to make a duplicate of the ''data'' rather than the list handles, then the Copy() method is recommended.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

==Methods==

===Setting list items===
cListBase and its derived classes provide the following methods for assigning items to the list:

====Add()====
<syntaxhighlight lang="cpp">
bool Add(int alItem)
bool Add(float afItem)
bool Add(double adItem)
bool Add(bool abItem)
bool Add(string asItem)
bool Add(cVector avItem)
bool Add(cPoint avItem)
bool Add(cRotator avItem)
</syntaxhighlight>
Creates a new item appended to the list. If the list is full or the item cannot be added, it returns false. If it was successfull appended, it returns true.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be added.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfFloats.Add(1.0f);
myListOfPoints.Add(cPoint(10, 15, 20));
// The new values are appended to the list.

// Example 2:
if (!listNumbers.Add(-1.0f)) Debug.Message(1, "Error - could not add to list!");
// The condition succeeds if Add failed.
</syntaxhighlight>

====Set()====
<syntaxhighlight lang="cpp">
bool Set(uint aulIndex, int alItem)
bool Set(uint aulIndex, float afItem)
bool Set(uint aulIndex, double adItem)
bool Set(uint aulIndex, bool abItem)
bool Set(uint aulIndex, string asItem)
bool Set(uint aulIndex, cVector avItem)
bool Set(uint aulIndex, cPoint avItem)
bool Set(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Assigns a new value to an indexed item in the list, if it exists. If the list is shorter than the index or the item cannot be added, this returns false. If it was successfull set, it returns true.
#''uint aulIndex'' - The index of the item to be changed.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
<syntaxhighlight lang="cpp">
// Example:
myListOfBools.Set(7, false);
// The bool at index 7 in the list becomes false, replacing the previous one.
</syntaxhighlight>

====Insert()====
<syntaxhighlight lang="cpp">
bool Insert(uint aulIndex, int alItem)
bool Insert(uint aulIndex, float afItem)
bool Insert(uint aulIndex, double adItem)
bool Insert(uint aulIndex, bool abItem)
bool Insert(uint aulIndex, string asItem)
bool Insert(uint aulIndex, cVector avItem)
bool Insert(uint aulIndex, cPoint avItem)
bool Insert(uint aulIndex, cRotator avItem)
</syntaxhighlight>
Inserts a new item into the list at the given index. (The item previous at that index becomes the next one.) If the given index is not a valid place to insert an item, then then return value will be false. Otherwise the item is inserted and it returns true.
#''uint aulIndex'' - The index where the new item will be inserted.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be inserted.
<syntaxhighlight lang="cpp">
// Example 1:
myListOfBools.Insert(7, false);
// The bool at index 7 in the list becomes false, displacing the previous one to index 8.

// Example 2:
if (!myList.Insert(10, "hello") myList.Add("hello");
// Attempts to insert the string at index 10, and if that fails the string is appended instead.
</syntaxhighlight>

====Concatenate()====
<syntaxhighlight lang="cpp">
bool Concatenate(cListBase aList)
bool Concatenate(int[] alArray)
bool Concatenate(float[] afArray)
bool Concatenate(double[] adArray)
bool Concatenate(bool[] abArray)
bool Concatenate(string[] asArray)
bool Concatenate(cVector[] avArray)
bool Concatenate(cPoint[] avArray)
bool Concatenate(cRotator[] avArray)
</syntaxhighlight>
Takes either a second list or array of the same type and appends it to this one. It first checks to make sure there is enough capacity. Returns true if items were successfully added, or false if not.
 If an array is supplied, new list items are created to match them. If a list is suplied the items are '''not duplicated''' - both lists refer to the same items in memory, and changing them will change both lists.
#''cListBase aList (or any list type), or an array of int[], float[], double[], bool[], string[], cVector[], cPoint[] or cRotator[]'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example 1:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

float[] arrayOfFloatsB = { 3.0f, 4.0f };
listOfFloatsA.Concatenate(arrayOfFloatsB);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 4.0f.

// Example 2:
cListFloat listOfFloatsA;
listOfFloatsA.Add(1.0f);
listOfFloatsA.Add(2.0f);

cListFloat listOfFloatsB;
listOfFloatsB.Add(3.0f);
listOfFloatsB.Add(4.0f);

listOfFloatsA.Concatenate(listOfFloatsB);
listOfFloatsA.Set(3, 99.9f);
// listOfFloatsA now contains 1.0f, 2.0f, 3.0f, 99.9f.
// listOfFloatsB now contains 3.0f, 99.9f.
</syntaxhighlight>

===Getting list items===
cListBase and its derived classes provide the following methods for retrieving items from the list:

====Get()====
<syntaxhighlight lang="cpp">
int Get(uint aulIndex)
float Get(uint aulIndex)
double Get(uint aulIndex)
bool Get(uint aulIndex)
string Get(uint aulIndex)
cVector Get(uint aulIndex)
cPoint Get(uint aulIndex)
cRotator Get(uint aulIndex)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, if it exists. If the item does not exist in the list, a default value will be returned instead, e.g. -1 or an empty string.
 See GetIfValid() if you want to be sure the item exists. You can also use an index operator (e.g. myList[i]) to get list items.
#''uint aulIndex'' - The index of the item to be retrieved.
<syntaxhighlight lang="cpp">
// Example:
cListString myToDoList;
myToDoList.Add("Paint the lines.");
myToDoList.Add("Cut the man.");

string myStringZero = myToDoList.Get(0);
string myStringLast = myToDoList.Get(myToDoList.LastIndex);
// myStringZero becomes the value from the start of the list.
// myStringLast becomes the value that happens to be at the end of the list.
</syntaxhighlight>

====GetIfValid()====
<syntaxhighlight lang="cpp">
bool GetIfValid(uint aulIndex, int &out alTarget)
bool GetIfValid(uint aulIndex, float &out afTarget)
bool GetIfValid(uint aulIndex, double &out adTarget)
bool GetIfValid(uint aulIndex, bool &out abTarget)
bool GetIfValid(uint aulIndex, string &out asTarget)
bool GetIfValid(uint aulIndex, cVector &out avTarget)
bool GetIfValid(uint aulIndex, cPoint &out avTarget)
bool GetIfValid(uint aulIndex, cRotator &out avTarget)
</syntaxhighlight>
Traverses the list and retrieves an item from the given index, as long as it is valid.
 The second parameter is an ''ouput'' parameter. If the item at the given index exists then '''the item is assigned to the Target &out parameter''', and the function returns true. If the item doesn't exist in the list, the function returns false.
 See Get() if you don't care about validation and just want to return the item.
#''uint aulIndex'' - The index of the item to be retrieved.
#''int alTarget, float afTarget, double adTarget, bool abTarget, string asTarget, cVector avTarget, cPoint avTarget, or cRotator avTarget'' - The variable, of the appropriate type, where the retrieved item will be '''stored'''.
<syntaxhighlight lang="cpp">
// Example:
int retrievedInteger;
if(!myListOfInts.GetIfValid(3, retrievedInteger)) retrievedInteger = -1;
// retrievedInteger will be assigned the value retrieved from index 3 in the list, if it exists.
// If it doesn't exist, the condition will succeed and retrievedInteger with be assigned -1 instead.
</syntaxhighlight>

====GetRandom()====
<syntaxhighlight lang="cpp">
int GetRandom()
float GetRandom()
double GetRandom()
bool GetRandom()
string GetRandom()
cVector GetRandom()
cPoint GetRandom()
cRotator GetRandom()
</syntaxhighlight>
Randomly selects an item from the list and returns it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors.
</syntaxhighlight>

====Pop()====
<syntaxhighlight lang="cpp">
int Pop()
float Pop()
double Pop()
bool Pop()
string Pop()
cVector Pop()
cPoint Pop()
cRotator Pop()
</syntaxhighlight>
Returns the last item in the list, and removes that item. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
int[] myArray = { 4, 8, 15, 16, 23 };
cListInt listNumbers = cListInt(myArray);
int lA = listNumbers.Pop();
int lB = listNumbers.Pop();
int lC = listNumbers.Pop();
// lA, lB, and lC have become 23, 16, and 15. myArray now contains only 4 and 8.
</syntaxhighlight>

====PopRandom()====
<syntaxhighlight lang="cpp">
int PopRandom()
float PopRandom()
double PopRandom()
bool PopRandom()
string PopRandom()
cVector PopRandom()
cPoint PopRandom()
cRotator PopRandom()
</syntaxhighlight>
Randomly selects an item from the list, returns it and them removes it. If the list is empty, a default value will be returned instead, e.g. -1 or an empty string.
<syntaxhighlight lang="cpp">
// Example:
string sRandomColor = listOfColors.GetRandom();
// The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
</syntaxhighlight>

====Copy()====
<syntaxhighlight lang="cpp">
cListInt Copy(cListInt aList)
cListFloat Copy(cListFloat aList)
cListDouble Copy(cListDouble aList)
cListBool Copy(cListBool aList)
cListVector Copy(cListVector aList)
cListPoint Copy(cListPoint aList)
cListRotator Copy(cListRotator aList)
</syntaxhighlight>
Returns a new list that is a duplicate of this list. The items in the new list are new items. Changing either list will not affect the other.
#''cListBase aList (or any list type)'' - The items to be added.
<syntaxhighlight lang="cpp">
// Example:
cListString listA;
listA.Add("one");
listA.Add("two");
listA.Add("three");

cListString listB = listA;

cListString listC;
listC = listA.Copy();

listA.Set(2, "banana");

// listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
// listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
</syntaxhighlight>

===Removing list items===
cListBase and its derived classes provide the following methods for removing items from the list: (See also: Pop() and PopRandom())

====RemoveAt()====
<syntaxhighlight lang="cpp">
bool RemoveAt(uint aulIndex)
</syntaxhighlight>
Traverses the list and removes the given index.
Returns true if the index was valid and was removed, or false if not.
#''uint aulIndex'' - The index of the item to be removed.
<syntaxhighlight lang="cpp">
// Example 1:
myList.RemoveAt(7);

// Example 2:
if (myList.RemoveAt(7)) myList.Append("something new");
// If the removal was successful, then a new value is appended.
</syntaxhighlight>

====RemoveItem()====
<syntaxhighlight lang="cpp">
bool RemoveItem(int alItem)
bool RemoveItem(float afItem)
bool RemoveItem(double adItem)
bool RemoveItem(bool abItem)
bool RemoveItem(string asItem)
bool RemoveItem(cVector avItem)
bool RemoveItem(cPoint avItem)
bool RemoveItem(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and removes the first matching item it finds. Returns true if the item was found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
Example 1:
myListOfBools.RemoveItem(false);
// The first instance of false in the list will be removed.

// Example 2:
int lRemoved = 0;
int[] myArray = { 4, 8, 0, 15, 16, 0, 23, 0 };
cListInt listNumbers = cListInt(myArray);
while (listNumbers.Remove(0))
{
lRemoved++;
DoStuff();
}
// The Remove() call will repeat until it returns false, at which point the value of lRemoved will be 3.
</syntaxhighlight>

====RemoveAll()====
<syntaxhighlight lang="cpp">
bool RemoveAll(int alItem)
bool RemoveAll(float aItem)
bool RemoveAll(double aItem)
bool RemoveAll(bool aItem)
bool RemoveAll(string aItem)
bool RemoveAll(cVector aItem)
bool RemoveAll(cPoint aItem)
bool RemoveAll(cRotator aItem)
</syntaxhighlight>
Searches the list for matching items and removes the all matching items. Returns true if any items were found and removed, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for and removed.
<syntaxhighlight lang="cpp">
// Example:
myListOfFloats.RemoveAll(0.0f);
// All the zeros will be removed from the list
</syntaxhighlight>

===Searching lists===
cListBase and its derived classes provide the following methods for searching for items in the list:

====Find()====
<syntaxhighlight lang="cpp">
int Find(int alItem)
int Find(float afItem)
int Find(double adItem)
int Find(bool abItem)
int Find(string asItem)
int Find(cVector avItem)
int Find(cPoint avItem)
int Find(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns the index of the first match. If the item is not found, -1 is returned instead.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

uint lIndexTwentyTwo = myListOfInts.Find(22);
uint lIndexFortyFour = myListOfInts.Find(44);
// lIndexTwentyTwo becomes 1. lIndexFortyFour becomes -1.
</syntaxhighlight>

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(int alItem)
bool Contains(float afItem)
bool Contains(double adItem)
bool Contains(bool abItem)
bool Contains(string asItem)
bool Contains(cVector avItem)
bool Contains(cPoint avItem)
bool Contains(cRotator avItem)
</syntaxhighlight>
Searches the list for a matching item and returns true if found, or false if not.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(33);

bool bHasTwentyTwo = myListOfInts.Find(22);
bool bHasFortyFour = myListOfInts.Find(44);
// bHasTwentyTwo becomes true. bHasFortyFour becomes false.
</syntaxhighlight>

====CountItem()====
<syntaxhighlight lang="cpp">
uint CountItem(int alItem)
uint CountItem(float afItem)
uint CountItem(double adItem)
uint CountItem(bool abItem)
uint CountItem(string asItem)
uint CountItem(cVector avItem)
uint CountItem(cPoint avItem)
uint CountItem(cRotator avItem)
</syntaxhighlight>
Searches the list for matching items and returns the number of matches found.
#''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be searched for.
<syntaxhighlight lang="cpp">
// Example:
cListString myListOfStrings;
myListOfStrings.Add("up");
myListOfStrings.Add("down");
myListOfStrings.Add("sideways");
myListOfStrings.Add("down");

int lNumDown = myListOfStrings.CountItem("down");
int lNumForward = myListOfStrings.CountItem("forward");
// lNumDown becomes 2. lNumForward becomes 0.
</syntaxhighlight>

===Numeric lists===
Some of the derived list classes dealing with numeric values provide the methods for arithmetic operations across the list:

====Min()====
<syntaxhighlight lang="cpp">
int Min()
float Min()
double Min()
bool Min()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns false if there is a false - like logical AND over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fSmallest = fRandomList.Min();
// fRandomList is assigned ten random floats, and whichever is the smallest is assigned to fSmallest.
</syntaxhighlight>

====Max()====
<syntaxhighlight lang="cpp">
int Max()
float Max()
double Max()
bool Max()
cVector Min()
cPoint Min()
</syntaxhighlight>
Returns the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - like logical OR over the list. For vectors and points, this evaluates and compares each square length.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
float fLargest = fRandomList.Max();
// fRandomList is assigned ten random floats, and whichever is the largest is assigned to fLargest.
</syntaxhighlight>

====FindMin()====
<syntaxhighlight lang="cpp">
uint FindMin()
</syntaxhighlight>
Returns the first index of the item with the lowest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lSmallest = fRandomList.FindMin();
// fRandomList is assigned ten random floats, and the index of the smallest is assigned to lSmallest.
</syntaxhighlight>

====FindMax()====
<syntaxhighlight lang="cpp">
uint FindMax()
</syntaxhighlight>
Returns the first index of the item with the highest value in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
<syntaxhighlight lang="cpp">
// Example:
cListFloat fRandomList;
for (uint i = 0; i < 10; i++) fRandomList.Add(Math.RandomFloat());
int lLargest = fRandomList.FindMax();
// fRandomList is assigned ten random floats, and the index of the largest is assigned to lLargest.
</syntaxhighlight>

====Sum()====
<syntaxhighlight lang="cpp">
int Sum()
float Sum()
double Sum()
bool Sum()
cVector Sum()
cPoint Sum()
</syntaxhighlight>
Returns the total of all the items in the list, added together. cListInt, cListFloat, cListDouble, cListBool, cListVector, and cListPoint only.
 For bools, this is returns true if there is a true - the same as logical OR. For vectors, this is equivalent to the combined path of each vector.
<syntaxhighlight lang="cpp">
Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lTot = listNumbers.Sum();
// lTot becomes 108.

// Example 2:
cListPoint listGridSteps;
listGridSteps.Add(cPoint(1, 0));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(0, 1));
listGridSteps.Add(cPoint(-1, 0));

cPoint vFinalPos = listGridSteps.Sum()
// This example imagines a puzzle involving steps on a grid. Each step is stored in a list of points and the final position is the sum of the list. (0,2 in this case.)
</syntaxhighlight>

====Average()====
<syntaxhighlight lang="cpp">
int Average()
float Average()
double Average()
bool Average()
cVector Average()
cPoint Average()
</syntaxhighlight>
Returns the mean average of all the items in the list. cListInt, cListFloat, cListDouble, cListBool, cListVector, cListPoint only.
 Note that for ints, the answer will be truncated. For bools, this basically returns true if there are more true items than false. For vectors this is like finding the "centre of balance" of some points.
<syntaxhighlight lang="cpp">
//Example 1:
int[] myArray = { 4, 8, 15, 16, 23, 42 };
cListInt listNumbers = cListInt(myArray);
int lAvg = listNumbers.Average();
// lAvg becomes 18.

// Example 2:
cListVector listGruntPos;
listGruntPos.Add(GetEntityPosVec("grunt1"));
listGruntPos.Add(GetEntityPosVec("grunt2"));
listGruntPos.Add(GetEntityPosVec("grunt3"));

SetEntityPosVec("orb", listGruntPos.Average());
// This example imagines an effect where an entity is positioned at the mid-point between 3 enemies.
</syntaxhighlight>

===Ordering lists===
cListBase and its derived classes provide the following methods for ordering items in the list:

====Swap()====
<syntaxhighlight lang="cpp">
bool Swap(uint aulA, uint aulB)
</syntaxhighlight>
Swaps the places of two items in the array. Returns false if either of the indeces are invalid, or true if the swap went ahead.
#''uint aulA'' - The index of the first item to be swapped.
#''uint aulB'' - The index of the second item to be swapped.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Swap(0, 1);
myListOfInts.Swap(1, 2);
// After the two swaps, the list is in numerical order.
</syntaxhighlight>

====Sort()====
<syntaxhighlight lang="cpp">
void Sort(abDescending = false)
</syntaxhighlight>
Re-orders a list of numbers, to put them in numerical order, using bubble sort. Bubble sort is simple but inefficient, so sorting large lists very frequently will have a performance impact. cListInt, cListFloat, cListDouble, cListVector, cListPoint only.
 For vectors, the list will be sorted by square length.
#''bool abDescending (optional, default = false)'' - If true, the items will be ordered highest-to-lowest, otherwise lowest-to-highest.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
myListOfInts.Add(33);
myListOfInts.Add(11);
myListOfInts.Add(22);
myListOfInts.Add(44);
myListOfInts.Sort();
// The list is now sorted into ascending numerical order.
myListOfInts.Sort(true);
// The list is now sorted into descending numerical order.
</syntaxhighlight>

====Shuffle()====
<syntaxhighlight lang="cpp">
void Shuffle()
</syntaxhighlight>
Changes the order of the list to a new, random order.
<syntaxhighlight lang="cpp">
// Example:
cListInt myListOfInts;
for (int i = 1; i <= 10; i++) myListOfInts.Add(i);
myListOfInts.Shuffle();
// The list now contains the numbers 1 to 10, in a random order with no repetition or missing numbers.
</syntaxhighlight>

===Arrays from lists===
cListBase and its derived classes provide the following methods for transforming lists into arrays:

====ToArray()====
<syntaxhighlight lang="cpp">
int[] ToArray()
float[] ToArray()
double[] ToArray()
string[] ToArray()
cVector[] ToArray()
cPoint[] ToArray()
cRotator[] ToArray()
</syntaxhighlight>
Makes an new array, where each element in the array is a copy of an item from the list, and returns the array.

====ToStringArray()====
<syntaxhighlight lang="cpp">
string[] ToArray()
</syntaxhighlight>
Makes an new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)

=Node classes=
The node classes contain the actual items in the lists and provide ways to access the data or links between nodes. Generally, it is '''not recommended''' to work with these directly, but use the functions of the list classes instead. More '''advanced users''' can extend the cListNodeBase class, or any class, and use it with cListGeneric.

Available node classes: <code>cListNodeInt</code>, <code>cListNodeFloat</code>, <code>cListNodeDouble</code>, <code>cListNodeBool</code>, <code>cListNodeString</code>, <code>cListNodeVector</code>, <code>cListNodePoint</code>, <code>cListRotator</code>

===Behaviours===
In the derived node classes, the default constructor creates a node with a default item, or an argument can be provided to set the initial value. For example, in the cListNodeInt class:
<syntaxhighlight lang="cpp">
cListNodeInt() // Creates an int node with value 0.
cListNodeInt(int alItem) // Creates an int node with value alItem.
</syntaxhighlight>

===Properties===
All dervied node classes have one public property, named Item:

====Item====
<syntaxhighlight lang="cpp">
int Item
float Item
double Item
bool Item
string Item
cVector Item
cPoint Item
cRotator Item
</syntaxhighlight>
The property Item can get or set the data item in the node, using the appropriate type.

===Methods===

====SetNext()====
<syntaxhighlight lang="cpp">
void SetNext(cListNodeBase@ ahNext)
</syntaxhighlight>
Assigns a handle to the next node. To break the link, assign null or use ClearNext().
#''cListNodeBase@ ahNext'' - A handle to an instance of cListNodeBase.

====GetNext()====
<syntaxhighlight lang="cpp">
cListNodeBase@ GetNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ClearNext()====
<syntaxhighlight lang="cpp">
void ClearNext()
</syntaxhighlight>
Returns the handle to the next node. If there isn't one, it will return null.

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Resets the handle to the next node to null

__FORCETOC__

HPL2/HPL2 Helper Scripts/String

2023-12-22T23:40:53Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_String.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=

The script file "HelperScripts_String.hps" provides some extended maths functionality for modders. The new String class contains additional string functions, including replacement, sequence generation and more.

Despite the name, this is not a string class itself, and does not contain text or replace the "string" type. String should be used similarly to Math, as a library of functions. For example:
<syntaxhighlight lang="cpp">
string welcomeText = "I bid you welcome to my cabinet of perturbation.";
string cabinetType = "liquor";
welcomeText = String.ReplaceAll(welcomeText, "perturbation", cabinetType);
</syntaxhighlight>

"HelperScripts_String.hps" also defines the Str class. The Str class is intended to provide something like a template parameter, or a loosely typed variable, for string formatting.

=String=

==Behaviours==
"HelperScripts_String.hps" script declares an object called '''String''', of the new script class cString. To access its methods, just use "String." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
String.Replace("catfish", "cat", "dog");
</syntaxhighlight>

==Properties==
String has no public properties.

==Methods==

===Length===
String provides the following methods for working with string sizes:

====IsEmpty()====
<syntaxhighlight lang="cpp">
bool IsEmpty(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns true if the string is empty ("").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check if empty.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
bool bA = String.IsEmpty(" ");
bool bB = String.IsEmpty(" ", trimAll);
// bA is assigned false. bB is assigned true, as the empty space is not counted.
</syntaxhighlight>

====Length()====
<syntaxhighlight lang="cpp">
uint Length(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Returns the number of characters in the string.
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), only the length of the string will be considered. This is the same as asString.length(). With any other trim option, whitespace and control characters will be not be counted. E.g. " " would count as empty if a trim option other than trimNone was used.
#''string asString'' - The string to check the length of.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example 1:
int lA = String.Length(" words words words ");
int lB = String.Length(" words words words ", trimEnd);
int lC = String.Length(" words words words ", trimAll);
// lA becomes 21, lB becomes 18 and lC becomes 17.

// Example 2:
while (sSleepy.Length() < 20) sSleepy += "z";
// The while loop continues until the string is at least 20 characters long.
</syntaxhighlight>

====Trim()====
<syntaxhighlight lang="cpp">
string Trim(string &in asString, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Removes whitespace and control characters from the beginning and end of a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the string will not be trimmed. With trimStart, whitespace and control characters will be removed from the start of the string. With trimEnd, whitespace and control characters will be removed from the end of the string. With trimAll (default), whitespace and control characters will be removed from both ends of the string.
#''string asString'' - The string to trim.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
string sSpooky = " sppoooky ";
sSpooky = String.Trim(aSpooky, trimStart);
// The initial spaces have been removed. sSpooky now equals "sppoooky ".
sSpooky = String.Trim(aSpooky);
// Now the trailing spaces have been removed too. sSpooky now equals "spoooky".
</syntaxhighlight>

===Parsing===
String provides the following methods for parsing strings:

====ToInt()====
<syntaxhighlight lang="cpp">
int ToInt(string asString)
</syntaxhighlight>
If possible, returns an integer converted from a string, else returns 0. This is the same as the normal global function StringToInt(), but is included here for consistency.

====ToFloat()====
<syntaxhighlight lang="cpp">
float ToFloat(string asString)
</syntaxhighlight>
If possible, returns a float converted from a string, else returns 0.0f. This is the same as the normal global function StringToFloat(), but is included here for consistency.

====ToBool()====
<syntaxhighlight lang="cpp">
bool ToBool(string asString)
</syntaxhighlight>
If possible, returns a boolean converted from a string, else returns false. This is the same as the normal global function StringToBool(), but is included here for consistency.

===Characters===
String provides the following miscellaneous methods for working with character codes:

====CharToString()====
<syntaxhighlight lang="cpp">
string CharToString(uint8 auiChar)
</syntaxhighlight>
Given an ASCII character code, this returns a string containing that single character. (Only works with ASCII, not full Unicode.)
#''uint8 auiChar'' - An ASCII character code to be converted to a string.
<syntaxhighlight lang="cpp">
// Example 1:
string sSymbols = String.CharToString(126) + String.CharToString(64) + String.CharToString(63);
// sSymbols now says "~@?".
</syntaxhighlight>

====StringToChar()====
<syntaxhighlight lang="cpp">
uint8 StringToChar(string asSingleChar)
</syntaxhighlight>
Given a single character string, this returns that character as an ASCII code. If the string is empty then 0 is returned (null character). If the string is longer than one character, the rest are ignored. (Only works with ASCII, not full Unicode.)
#''string asSingleChar'' - A string containing a character to be converted to a character code.
<syntaxhighlight lang="cpp">
// Example:
uint8 uiCharacter = String.StringToChar(sSomeText);
if (uiCharacter >= 48 && ul8Character <= 57) DoStuff();
// The condition succeeds if the first character of sSomeText is a numeric digit (ASCII codes 48-57).
</syntaxhighlight>

====CharArrayToString()====
<syntaxhighlight lang="cpp">
string CharArrayToString(uint8[] ausCharArray, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given an array of ASCII codes, this returns those character joined into a string. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the array will be included. With trimStart, any whitespace or control characters at the start of the array will be excluded. With trimEnd, any whitespace or control characters at the end of the array will be excluded. With trimAll, any whitespace or control characters at either end of the array will be excluded.
#''uint8[] ausCharArray'' - An array of ASCII character codes (unsigned 8bit ints), to be joined.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
See StringToCharArray() for an example. 

====StringToCharArray()====
<syntaxhighlight lang="cpp">
uint8[] StringToCharArray(string asString, enumStringTrim aTrimOption = trimNone)
</syntaxhighlight>
Given a string, this splits the string and returns it as an array of ASCII codes. (Only works with ASCII, not full Unicode.)
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone (default), any whitespace or control characters in the string will be included. With trimStart, any whitespace or control characters at the start of the string will be excluded. With trimEnd, any whitespace or control characters at the end of the string will be excluded. With trimAll, any whitespace or control characters at either end of the string will be excluded.
#''string asString'' - A string to be split.
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimNone)
<syntaxhighlight lang="cpp">
// Example:
string Rot13(string asInput)
{
uint8[] chars = String.StringToCharArray(asInput, trimAll);
for (uint i = 0; i < chars.length(); i++)
{
if (chars[i] >= 65 && chars[i] <= 90 || chars[i] >= 141 && chars[i] <= 172)
{
chars[i] += 13;
if (chars[i] > 90 && chars[i] < 141 || chars[i] > 172)
{
chars[i] -= 26;
}
}
}
return String.CharArrayToString(chars );
}
// This example is a whole Rot13 function. The string arg asInput is broken into an array of chars. Any char that is a upper or lower case alphabet letter is moved 13 characters. Then the char array is made back into a string and returned.
</syntaxhighlight>

===Case===
String provides the following methods for changing the case of a string:

====ToUpper()====
<syntaxhighlight lang="cpp">
string ToUpper(string asString)
uint8 ToUpper(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as upper case. If any character is a lower case letter, it will be swapped for upper case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to upper case.
<syntaxhighlight lang="cpp">
// Example 1:
string sUpper = String.ToUpper("Dark Descent");
// sUpper is assigned "DARK DESCENT".

// Example 2:
if (String.ToUpper(sSomeTextA) == String.ToUpper(sSomeTextB))
// The condition succeeds if sSomeTextA and sSomeTextB are equal, regardless of their capitalisation.
</syntaxhighlight>

====ToLower()====
<syntaxhighlight lang="cpp">
string ToLower(string asString)
uint8 ToLower(uint8 auiChar)
</syntaxhighlight>
Given a string or a character code, this returns the character(s) as lower case. If any character is a upper case letter, it will be swapped for lower case. Otherwise they are unchanged. (Only works with ASCII, not full Unicode.)
#''string asString, uint8 auiChar'' - A string or a single character code to be changed to lower case.
<syntaxhighlight lang="cpp">
// Example:
string sLower = String.ToLower("Dark Descent");
// sLower is assigned "dark descent".
</syntaxhighlight>

===Searching===
String provides the following methods for changing the case of a string:

====Contains()====
<syntaxhighlight lang="cpp">
bool Contains(string asString, string asSubString)
</syntaxhighlight>
Returns true if asSubString can be found in asString. This is the same as the normal global function StringContains(), but is included in String for consistency.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
<syntaxhighlight lang="cpp">
// Example:
if (String.Contains(sCurrentObjective, "thalers");
// The condition succeeds if the string sCurrentObjective contains the substring "thalers".
</syntaxhighlight>

====Find()====
<syntaxhighlight lang="cpp">
int Find(string asString, string asSubString, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches for a substring within a string, and the returns the index of the first character of the first instance of the substring.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asSubString'' - The string to search for.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
int lA = String.Find("Grunt", "run");
int lB = String.Find("Agrippa", "RIP", caseInsensitive);
int lC = String.Find("Herbert", "er");
int lD = String.Find("Herbert", "er", dirFromEnd);
// lA is assigned 1. lB is assigned 2.
// lC is assigned 1, but searching from the end lD is assigned 4.
</syntaxhighlight>

===Substrings===
String provides the following methods for working with parts of strings:

====Sub()====
<syntaxhighlight lang="cpp">
string Sub(string asString, uint aulStart, uint aulCount)
string Sub(string asString, uint aulStart)
</syntaxhighlight>
Returns part of a string. This is the same as the normal global function StringSub(), except that aulCount can be omitted. If aulCount is specified, the substring returned starts at aulStart and proceeds for aulCount characters. If aulCount is omitted then the substring starts at aulStart and proceeds to the end of the original string.
#''string asString'' - The string to get the substring from.
#''uint aulStart'' - The index of the character that is the start of the substring.
#''uint aulCount'' - The number of characters in the substring. (Optional, default = the remaining length of the string)
<syntaxhighlight lang="cpp">
// Example:
string sA = String.Sub("grunt", 1, 3);
string sB = String.Sub("grunt", 1);
// sA is assigned "run". sB is assigned "runt".
</syntaxhighlight>

====Replace()====
<syntaxhighlight lang="cpp">
string Replace(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive, enumStringDirection aDirOption = dirFromStart)
</syntaxhighlight>
Searches through a string and if it finds an instance of a given substring, it replaces it with another. Replace() replaces the first instance found. To replace all instances, consider ReplaceAll().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aDirOption can be omitted, or optionally can be either dirFromStart, or dirFromEnd. With dirFromStart (default), the string is searched from the left, and the index returned is the first instance. With dirFromEnd, the string is searched from the right, and the index returned is the last instance.
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringDirection aDirOption'' - dirFromStart or dirFromEnd. (Optional, default = dirFromStart)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.Replace(sMyStringA, "cat", "dog");
string sMyStringC = String.Replace(sMyStringA, "cat", "dog", dirFromEnd);
// sMyStringB becomes "dogfish catfood". sMyStringC becomes "catfish dogfood".
</syntaxhighlight>

====ReplaceAll()====
<syntaxhighlight lang="cpp">
string ReplaceAll(string asString, string asFind, string asReplace, enumStringCase aCaseOption = caseSensitive)
</syntaxhighlight>
Searches through a string and replaces all instances of a substring with another. To avoid an infinite loop, asReplace can't contain a match to asFind it would. Consider using Replace() instead.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
#''string asString'' - The string to search within.
#''string asFind'' - The string to search for.
#''asReplace'' - The string that will replace asFind if it is found.
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
<syntaxhighlight lang="cpp">
// Example:
string sMyStringA = "catfish catfood";
string sMyStringB = String.ReplaceAll(sMyStringA, "cat", "dog");
// sMyStringB becomes "dogfish dogfood".
</syntaxhighlight>

====Format()====
<syntaxhighlight lang="cpp">
string Format(string asString, Str[] argArray)
string Format(string asString, Str arg0, Str arg1, ... Str arg7)
</syntaxhighlight>
A minimal version of the string formatting methods found in other languages. It doesn't provide number formating options, but it does allow an arbirtrary number of variables to be inserted into a string, regardless of data type, using the Str class. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. This is the method used by the cDebug class.
 Format() returns a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero. If an argument is supplied but the text doesn't contain a corresponding token, then the argument won't be included. If the text contains a token but not corresponding argument is supplied, then the token will remain in the output text.
 Up to eight individual Str arguments can be provides, or an array of Str. (Unfortunately, anonymous arrays as arguments are not supported, so the array must be declared.)
#''string asString'' - A template string containing tokens ("{i}") to be replaced by the other arguments.
#''argArray or arg0'' - An array of Str instances, or a single Str instance, to replace tokens in the string.
#''arg1 - arg7'' - If not using an array, an additional 7 single Str arguments can be optionally given.
<syntaxhighlight lang="cpp">
// Example 1:
string sNewString = String.Format("I got {0} problems but this script ain't {1}.", Str(99), Str("one"));
// sNewString is assigned "I got 99 problems but this script ain't one."

// Example 2:
Str[] myArray = { Str("Daniel"), Str("London"), Str("Mayfair") };
string myOutput = String.Format("My name is {0}, I live in {1} at... at... {2}...", myArray);
// myOutput becomes "My name is Daniel, I live in London at... at... Mayfair..."
</syntaxhighlight>

===Arrays and lists===
String provides the following methods for splitting and joining collections of strings:

====Join()====
<syntaxhighlight lang="cpp">
string Join(string[] asStringArray, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
string Join(cListBase asGenericList, string asSeparator = "", enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a collection of strings, this returns them joined into a single string. The collection can be a string array (string[]), a list of strings (cListString), or any type other type of list. (The ToStringArray() method of the cListBase class is used, which in turn calls the ToString() method of each node. For most list classes this will return valid strings, but if the instanced list is itself cListBase or cListGeneric, empty strings will be returned.)
 Optionally, a separator string can be included, which will be inserted between each item. If omitted, asSeparator defaults to "" - i.e., no separator. Example uses could be " " or "_".
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, the strings in the array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings before they are joined. With trimEnd, whitespace will be removed from the end of the strings before they are joined. With trimAll (default), whiltespace will be removed from both ends of the strings before they are joined. Additionally any empty strings will be ignored unless trimNone is used.
#''string[] asStringArray, cListString asListString'' - An array of strings, a list of strings, or any other list type that can output strings, to be joined.
#''stromg asSeparator'' - A substring to insert between each joined string. (Optional, default = "")
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example 1:
float[] fNumbers = { 2.33f, 3.44f, 4.55f, 5.66f };
string sNumberText = String.Join(fNumbers, " >> ");
// sNumberText will read "2.33 >> 3.44 >> 4.55 >> 5.66".

// Example 2:
cListString sJumble = String.Join(String.SplitToList("The Inner Sanctum, my most precious chamber, Daniel.").Shuffle(), " ");
// sJumble becomes the words of the string, in a random order. First the string is split into a list of strings, the list's Shuffle() method is called, and the result is passed to Join().
</syntaxhighlight>

====SplitToList()====
<syntaxhighlight lang="cpp">
cListString SplitToList(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into a list of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned list contains the individual words in the string.
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the substring must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting list will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting list. With trimEnd, whitespace will be removed from the end of the strings in the resulting list. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
#''string asString'' - A string to be split into a list.
#''string asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''enumStringCase aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''enumStringTrim aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
<syntaxhighlight lang="cpp">
// Example:
cListString myListA = String.SplitToList("cat_dog_catfish_dogfish", "_");
cListString myListB = String.SplitToList("cat_dog_catfish_dogfish", "_Dog");
cListString myListC = String.SplitToList("cat_dog_catfish_dogfish", "_Dog", caseInsensitive);
// myListA is created with the items "cat", "dog", "catfish" and "dogfish".
// myListB is created with the no items, as the delimiter is not found with the defaul caseSensitive option.
// myListC is created with the items "cat", "_catfish" and "fish".
</syntaxhighlight>

====SplitToArray()====
<syntaxhighlight lang="cpp">
string[] SplitToArray(string asString, string asDelimiter = " ", enumStringCase aCaseOption = caseSensitive, enumStringTrim aTrimOption = trimAll)
</syntaxhighlight>
Given a string and a substring to use as a delimiter, this returns the string split up into an array of substrings. If the delimiter is omitted then it defaults to " " - a single space, so the returned array contains the individual words in the string. Consider also: SplitToList().
 aCaseOption can be omitted, or optionally can be either caseSensitive, or caseInsensitive. With caseSensitive (default), the delimiter must match exactly, including the case. With caseInsensitive, the capitalisation does not matter. (E.g. "Foobar" matches with "fooBar").
 aTrimOption can be omitted, or optionally can be either trimNone, trimStart, trimEnd or trimAll. With trimNone, strings in the resulting array will not be trimmed. With trimStart, whitespace will be removed from the start of the strings in the resulting array. With trimEnd, whitespace will be removed from the end of the strings in the resulting array. With trimAll (default), whiltespace will be removed from both ends of the strings in the resulting array. Additionally any empty strings will be ignored unless trimNone is used.
 (The max length of the array is 256, but advanced users could edit that if needed.)
#''string asString'' - A string to be split into an array.
#''asDelimiter'' - A substring to search for in asString, for the boundary of each split. (Optional, default = " ")
#''aCaseOption'' - caseSensitive or caseInsensitive. (Optional, default = caseSensitive)
#''aTrimOption'' - trimNone, trimStart, trimEnd, or trimAll. (Optional, default = trimAll)
For an example, see SplitToList() 

===Sequences===
String provides the following methods for working with numbered string sequences:

====StringRange()====
<syntaxhighlight lang="cpp">
string[] StringRange(string asPrefix, uint alRangeFirst, uint alRangeLast, string asSuffix)
string[] StringRange(string asPrefix, string asRangeFirst, string asRangeLast, string asSuffix)
</syntaxhighlight>
Returns an array of strings where each string in the array is made up of a prefix, followed by an iterator from given range, and then a suffix. The prefix and/or suffix can be "".
 Accepts the iterator range as either integers or characters, expressed as an inclusive min and inclusive max. Any integers or any ASCII characters could be used, as long as the min/first is less than the max/last.
#''string asPrefix'' - A string to add at the start of the output strings.
#''int alRangeFirst, string asRangeFirst'' - An integer or a single character string for the start of the iteration. (inclusive).
#''int alRangeLast, string asRangeLast'' - An integer or a single character string for the end of the interation (inclusive).
#''string asSuffix'' - A string to add at the end of the output strings.
<syntaxhighlight lang="cpp">
// Example 1:
string[] sDoorNames = String.StringRange("door", 2, 5);
for (uint i = 0; i < sDoorNames.length(); i++) SetSwingDoorLocked(sDoorNames, true, true);
// Creates an array of strings containing "door2", "door3", "door4" and "door5", and passes each of them to SetSwingDoorLocked().

// Example 2:
string[] sStuffAndJunk = StringRange("stuff_", "A", "C", "_andJunk");
// sStuffAndJunk is assigned with the strings "stuff_A_andJunk", "stuff_B_andJunk" and "stuff_C_andJunk".
</syntaxhighlight>

====IntToStringFixedDigits()====
<syntaxhighlight lang="cpp">
string IntToStringFixedDigits(uint aulNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
string IntToStringFixedDigits(int alNumber, uint8 auiDigits, enumLimitType aLimitOption = limitClamped)
</syntaxhighlight>
Returns a string representing an unsigned or positive int, with the specified number of characters, adding leading zeros if needed. aulNumber is the number to convert. auiDigits is the number of digits. E.g. 42 as 3 digits returns the string "042". auiDigits is an unsigned 8-bit int (0-255), because the max uint is only 10 digits. (Hey, if you want to try any make a string that's 2^32 followed by 245 zeros, that's none of my business!)
 aLimitOption is optional and can be omitted, or it can be limitFree, limitClamped or limitWrapped. With limitFree, the number is not clamped, so auiDigits is a minimum. E.g. 1 as 2 digits returns "01" but 123 as 2 digits returns "123". With limitClamped (default), the number will be clamped within the range of the digits. E.g. 123 as 2 digits returns "99". With limitWrapped, the number will be modulated. E.g. 123 as 2 digits returns "23".
#''uint aulNumber, int alNumber' - An unsigned integer to be respresented in the string. If the supplied int is signed and less than zero, it will be treated as zero.
#''uint8 auiDigits'' - The min number of digits to include in the string.
#''enumLimitType aLimitOption'' - Can be limitFree, limitClamped or limitWrapped. (Optional, default = limitClamped)
<syntaxhighlight lang="cpp">
// Example 1:
string sNum = String.IntToStringFixedDigits(1188, 4, limitWrapped);
// sNum becomes "0088".

// Example 2:
for (uint i = 1; i <= 12; i++) SetSwingDoorLocked("door_" + String.IntToStringFixedDigits(i, 3), true, true);
// This example imagines that the level has 12 doors named in the style "door_001", "door_002", ... "door_009", "door_010", "door_011", "door_012".
</syntaxhighlight>

=Str class=
The Str class is used in the String.Format() and Debug.Message() methods.
 It's purpose is to provide something like a template parameter, or a loosely typed variable, for string formatting. The main goal is just to let modders pass values for string formatting without requiring hundreds of overloads. It's definitely clunkier in debug mode, but outside of debug mode it's more efficient.

==Behaviours==
The Str constructors can be passed a reference to a single string, int, uint, float, double, bool, cVector, cRotator, cPoint, cBezier, or cSpline.
<syntaxhighlight lang="cpp">
// Example:
Str(3)
Str(myInt)
Str(myVector)
</syntaxhighlight>

==Properties==
Str has no public properties.

==Methods==
The only method is the ToString() function:

====ToString()====
<syntaxhighlight lang="cpp">
string ToString()
</syntaxhighlight>
Returns the stored variable as a string.
<syntaxhighlight lang="cpp">
// Example 1:
Debug.Message(3, "Created new rotator {0} for puzzle #{1}.", Str(myRotator), Str(myInt));

// Example 2:
SetLevelDoorLockedText("BigDoor", "BigDoorMessages", String.Format("Door_Zone{0}_Type{1}", Str(doorZone), Str(doorType)));
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Spawner

2023-12-22T23:28:04Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Spawner.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script class cSpawner provides methods for spawning entities and particle systems at specific vector positions.

===Spawn area===
The normal global functions provided by HPL2 only allow scripts to place objects at an existing Script Area. Spawner makes use of this and teleports the objects into the desired position afterwards.

There are three options for using Spawner, regarding a Spawn Area:
# Simply add a Script Area to the level named "SpawnArea", anywhere, any size.
# Tell Spawner to use a Script Area that already exists in the map, anywhere, any size, regardless of any other purpose.
# Tell Spawner to use multiple Script Areas placed in the map especially. This is only useful for semi-random rotation.

The default named Area is "SpawnArea" - you can change this using the SpawnArea property in script.
<syntaxhighlight lang="cpp">
Spawner.SpawnArea = "SomeOtherArea";
</syntaxhighlight>
Whatever it is called, there must be designated Script Area in the map, ''somewhere'', whose name matches SpawnArea. It doesn't matter what size it is or where it is located, as long as it exists.

===Spawning with shapes===
As well as spawning enties at specific positions, Spawner can also spawn entities randomly within a box or sphere shape, or spread evenly along a curve. It can also spawn particle systems at specific places or on a curve.

===Spawning with rotation===
It isn't possible to set the world rotation of an entity through script alone. However, spawned items will match the rotation of the whatever Script Area they were spawned at.

The SpawnArea propery allows one specific area to be set, but the [[HPL2/HPL2_Helper_Scripts/Spawner#SetSpawnArea.28.29|SetSpawnArea()]] ''method'' will accept an array or list of area names. When more than one Spawn Area is set, each spawned item will choose a different one at random. Having multiple Spawn Areas has no advantage other than having multiple sources for rotation.

For example, if the desired outcome is to spawn many debris objects with random-ish rotations, multiple Script Areas should be created in the level and given specific names and different rotations. It doesn't matter what size or location they are, only their rotation matters. In script, they should all be assigned with [[HPL2/HPL2_Helper_Scripts/Spawner#SetSpawnArea.28.29|SetSpawnArea()]], and then each spawned item will take on the rotation of one of the areas at random.

===Particles & temporary entities===
In order to spawn particle systems, Spawner spawns a "temp entity" - an invisible entity that the particle system is attached to. The number of temp entities is limited (256 by default) and when the full number is reached, older ones will be recycled.

If Spawner is used to create entities without specifying a name for them, they will be treated like temp entities too.

The entity file used for temp entities is called "SpawnerTemp.ent" and is located in the ""HPL2HelperScripts" folders. This can be changed using the TempEntityFile property, if required for some reason.

===Save data===
Spawner does not save any data of its own. By default, entities created by Spawner will be saved along with the save game and Spawner will have no need to remember them on the next play session. The SaveEntities property can be used to change this behaviour at run-time. Its default is true.
<syntaxhighlight lang="cpp">
Spawner.SpawnEntityAtPos("ent1", "spookyChair.ent", cVector(0.0f, 0.0f, 0.0f)); // This new entity will save by *default*.
Spawner.SaveEntities = false;
Spawner.SpawnEntityAtPos("ent2", "spookyTable.ent", cVector(2.0f, 0.0f, 0.0f)); // This new entity will *not* save, specifically.
Spawner.SaveEntities = true;
Spawner.SpawnEntityAtPos("ent3", "spookyCrate.ent", cVector(4.0f, 0.0f, 0.0f)); // This new entity *will* save, specifically.
</syntaxhighlight>

===Advanced info===
'''Advanced users''' may wish to examine "HelperScripts_Spawner.hps" to see how it makes use of other script classes. There are also some private variables that could to tweaked to fit the needs of a specific project, such as the default names for entities and the maximum number of temp entities allowed.

=Spawner=
Spawner is the name of the object that manages spawning entities at specific map locations.

==Behaviours==
"HelperScripts_Spawner.hps" declares an object called '''Spawner''', of the new script class cSpawner. To access its methods, just use "Spawner." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
Spawner.SpawnEntityAtPos("bigThing", "bigThing.ent", cVector(1.1f, 2.2f, 3.3f));
</syntaxhighlight>

==Properties==
Spawner provides the following properties:

====SaveEntities====
<syntaxhighlight lang="cpp">
string SaveEntities
</syntaxhighlight>
The bool property SaveEntities can be used to specify whether entities and particle systems spawned by Spawner will be saved as part of the save game. (Default = true)
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntityAtPos("ent1", "spookyChair.ent", cVector(0.0f, 0.0f, 0.0f)); // This new entity will save by default.
Spawner.SaveEntities = false;
Spawner.SpawnEntityAtPos("ent2", "spookyTable.ent", cVector(2.0f, 0.0f, 0.0f)); // This new entity will ''not'' save, specifically.
Spawner.SaveEntities = true;
Spawner.SpawnEntityAtPos("ent3", "spookyCrate.ent", cVector(4.0f, 0.0f, 0.0f)); // This new entity ''will'' save, specifically.
</syntaxhighlight>

====SpawnArea====
<syntaxhighlight lang="cpp">
string SpawnArea
</syntaxhighlight>
The string property SpawnArea can get or set the named Script Area used for spawning entities. (Default = "SpawnArea")
 (The advantage of using the SpawnArea property is that it can just be set to any Script Area that happens to exist in the map.)
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnArea = "LibraryEntranceTriggerB";
// Spawner will use the Script Area named "LibraryEntranceTriggerB" instead of the default name.
</syntaxhighlight>

====TempEntityBaseName====
<syntaxhighlight lang="cpp">
string TempEntityBaseName
</syntaxhighlight>
The string property TempEntityBaseName can get or set the prefix used when naming temp entities. (Default = "SpawnerTemp")
 If TempEntityBaseName is "SpawnerTemp" then temp entities will have names like "SpawnerTemp_0", "SpawnerTemp_1", etc..
 Note: This can only be changed before Spawner has actually spawned any temp entities, otherwise it would not be able to update or recycle them.
<syntaxhighlight lang="cpp">
// Example:
Spawner.TempEntityBaseName = "MySpecialEntityName";
// Spawner will now create temporary entities with names like "MySpecialEntityName_0", "MySpecialEntityName_1", etc..
</syntaxhighlight>

====TempEntityFile====
<syntaxhighlight lang="cpp">
string TempEntityFile
</syntaxhighlight>
The string property TempEntityFile can get or set the .ent file used for spawning temporary entities for particle systems. (Default = "SpawnerTemp.ent")
 The only reason to change TempEntityFile is if there is a specific entity that should be used instead.
 Note: This can only be changed before Spawner has actually spawned any temp entities, otherwise it would not be able to update or recycle them.
<syntaxhighlight lang="cpp">
// Example:
Spawner.TempEntityFile = "CustomTempEnt.ent";
// Spawner will attempt to spawn temp entities from the file "CustomTempEnt.ent" instead of the default file.
</syntaxhighlight>

==Methods==
Spawner provides the following methods:

===Spawning entities===

====SpawnEntityAtPos()====
<syntaxhighlight lang="cpp">
bool SpawnEntityAtPos(string asNewEntityName, string asEntityFile, cVector avPosition)
bool SpawnEntityAtPos(string asNewEntityName, cListString@ ahEntityFileList, cVector avPosition)
bool SpawnEntityAtPos(string asNewEntityName, string[] asEntityFileArray, cVector avPosition)
</syntaxhighlight>
Spawns an entity at a specific vector position. If an entity with that name already exists, it will be recycled. That is, it will be teleported into the new position. SpawnEntityAtPos returns true if the entity was recycled, or false if a new entity was created.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
#''string asNewEntityName'' - The name that the new entity will be given. Should either be unique, or an existing entity will be recycled instead.
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''cVector avPosition'' - A 3d vector position in the map to spawn the entity.
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntityAtPos("AcmeAnvil", "anvil.ent", Math.GetPlayerPosVec() + cVector(0.0f, 3.0f, 0.0f));
// An entity of the type "anvil.ent" spawns 3m above the player's location.
</syntaxhighlight>

====SpawnEntitiesInBox()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cVector avBoxMin, cVector avBoxMax)
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cVector avBoxMin, cVector avBoxMax)
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cVector avBoxMin, cVector avBoxMax)
</syntaxhighlight>
Spawns a quantity of entities a random positions within a box shape defined by a pair of vectors (similar to the box shaped starting position in the particle editor). If the box is sized zero in one dimension then that is effectively a rectangle, so this can also be used spawn objects on a plane.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If the script needs to refer to the entities by name later, use asEntityBaseName to give them specific names.
 SpawnEntitiesInBox returns true if any entities were recycled, or false if all the entities are newly created.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to spawn in the box.
#''cVector avBoxMin'' - The minimum extent of the box.
#''cVector avBoxMax'' - The maximum extent of the box.
<syntaxhighlight lang="cpp">
// Example:
cListString listJunkProps;
listJunkProps.Add("wooden_board02.ent");
listJunkProps.Add("tongs.ent");
listJunkProps.Add("hammer.ent");
listJunkProps.Add("chisel.ent");
listJunkProps.Add("basket.ent");
listJunkProps.Add("flask01.ent");
listJunkProps.Add("dungeon_small01.ent");
listJunkProps.Add("brick.ent");
listJunkProps.Add("brick.ent");
listJunkProps.Add("brick.ent");

Spawner.SpawnEntitiesInBox("Junk_A", listJunkProps, 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24 random junk items are selected from the list and spawned in a square, with names "Junk_A_0" to "Junk_A_23".
// Note that "brick.ent" is three times more likely to spawn than the others.
</syntaxhighlight>

====SpawnEntitiesInSphere()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cVector avOrigin, float afRadius)
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cVector avOrigin, float afRadius)
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cVector avOrigin, float afRadius)
</syntaxhighlight>
Spawns a quantity of entities a random positions within a sphere shape defined by a centre vector and a radius.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If you need to know the names of the entities to refer to them later, use asEntityBaseName.
 SpawnEntitiesInSphere returns true if any entities were recycled, or false if all the entities are newly created.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to spawn in the sphere.
#''cVector avOrigin'' - The centre of the sphere.
#''cVector afRadius'' - The radius of the sphere.
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntitiesInSphere("MegaOrb", "orb.ent", 1000, Math.GetPlayerPosVec(), 4.0f);
SetPlayerSanity(0.0f);
// One thousand orbs have spawned around the player, placing them at the centre of an 8m wide MegaOrb. The player had no chance to remain sane in such circumstances.
// Note: if no string was given for asEntityBaseName, then the number of entities spawned would be limited to the temp entity max (default = 256).
</syntaxhighlight>

====SpawnEntitiesOnSpline()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
Spawns a quantity of entites evenly spaced along a spline.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If the names of the entities are needed to refer to them later or update their position, use asEntityBaseName.
 SpawnEntitiesOnSpline returns true if any entities were recycled, or false if all the entities are newly created.
 afPhase is optional. It can be used to adjust the spread of the entities on the curve with a number between 0.0f and 1.0f, or it can be omitted. If it is omitted, or less than zero, then the default spacing will be used.
 The default spacing is the "full spread" - that is to say the first entity will be spawned at the start of the curve, the last entity at the very end, and all the others evenly in between.
 However, if value between 0.0f and 1.0f is used for afPhase, then the entities will be spawned within their own division of the curve, with the phase 0.0f - 1.0f specifying how far through that division it will appear.
 The following diagram illustrates the phase option:
<syntaxhighlight>
|1----2----3----4| <- default spacing: no phase, full spread.
|1---2---3---4---| <- phase = 0.0f, each object at the start of its division.
|-1---2---3---4--| <- phase = 0.25f, each object 1/4 of the way through its division.
|--1---2---3---4-| <- phase = 0.5f, each object 1/2 of the way through its division.
|---1---2---3---4| <- phase = 0.75f, each object 3/4 of the way through its division.
|1---2---3---4---| <- phase = 1.0f is the same as phase = 0.0f.
</syntaxhighlight>
 To update the position of the spawned entities without respawning them, for example if the spline or phase has changed, see UpdateEntitiesOnSpline().
 You can easily use SpawnEntitiesOnSpline() with a single Bezier or a straight line between two points, depending on how you construct your spline. See the examples, or see cSpline and cBezier classes for more information.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to be placed on the spline.
#''cSpline@ ahSpline'' - A spline to place entities on.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline("WigglyPathChair", "chair.ent", 10, vBigWigglyPath);
// 10x chair.ent have been spawned on the existing spline curve vBigWigglyPath.

// Example 2:
SpawnEntitiesOnSpline("rock.ent", 16, cSpline(cVector(2.0f, 2.0f, 10.0f), cVector(4.0f, 2.0f, 10.0f));
// 16x rock.ent have been spawned in a line shape.
// The line is formed from a new cSpline defined by two cVectors.
// The entities were not named, so temp entity names have been used. This means that they cannot be updated and may be recycled.

// Example 3:
cSpline vFloatyRockArch = cSpline(cVector(2.0f, 0.0f, 10.0f), cVector(2.0f, 3.0f, 10.0f), cVector(4.0f, 3.0f, 10.0f), cVector(4.0f, 0.0f, 10.0f));

cListString listRockTypes;
for (uint i = 0; i < 5; i++) listRockTypes.Add("rock_" + i + ".ent");

Spawner.SpawnEntitiesOnSpline("FloatyRockArchEnt", listRockTypes, 16, vFloatyRockArch);
// 16x rocks have been spawned in an arch shape.
// The arch is formed from a new cSpline defined by four cVectors, making a cubic bezier.
// Each rock entity was selected at random from one of five created in the list.
</syntaxhighlight>

===Spawning particles===

====SpawnParticlesAtPos()====
<syntaxhighlight lang="cpp">
bool SpawnParticlesAtPos(string asNewPSName, string asPSFile, cVector avPosition)
bool SpawnParticlesAtPos(string asNewPSName, cListString@ ahPSFileList, cVector avPosition)
bool SpawnParticlesAtPos(string asNewPSName, string[] asPSFileArray, cVector avPosition)
</syntaxhighlight>
Spawns a particle system at a specific vector position.
 The .ps file can be given as a specific string, e.g. "ps_bubbles.ps", or it can be a list or array or strings. If a list or array is given, the .ps file that spawns will be chosen at random from the list or array.
 In order to place a particle system at an arbitrary location, a temp entity is used, using the msTempEntNameBase. If the maximum number of temp entities already exist, one will be recycled in the new position. SpawnParticlesAtPos returns true if the temp entity was recycled, or false if a new entity was created.
 If a particle system already exists with the given name, then it will be destroyed and replaced.
#''string asNewPSName'' - The name that the new particle system will be given. Should either be unique, or an existing system will be recycled instead.
#''string asPSFile, cListString@ ahPSFileList, string[] asPSFileArray'' - A string, an array of strings, or a list of strings containing one or more .ps files.
#''cVector avPosition'' - A 3d vector position in the map to spawn the entity.
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnParticlesAtPos("FloatyFlame", "ps_fire_candle.ps", cVector(23.0f, 2.25f, 14.5f));
// A candle flame will be spawned at the given vector position, using a temp entity.

// Example 2:
string[] arrayFlameTypes = { "ps_fire_candle.ps", "ps_fire_candle_red.ps", "ps_fire_candle_blue.ps" };

Spawner.SpawnParticlesAtPos("FloatyFlame", listFlameTypes, cVector(23.0f, 2.25f, 14.5f));
// A candle flame will be spawned at the given vector position, using a temp entity.
// The .ps file will be selected at random from the array.
</syntaxhighlight>

====SpawnParticlesOnSpline()====
<syntaxhighlight lang="cpp">
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", string asPSFile, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", cListString ahPSFileList, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", string[] ahPSFileArray, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
Spawns a quantity of particle systems evenly spaced along a spline. The ahSpline argument should refer to an existing cSpline variable if the positions of the particles should need to be updated later. See the examples, or see cSpline for further information on creating splines. To update the position of the spawned entities without respawning them, for example if the spline or phase has changed, see UpdateEntitiesOnSpline(). This will also move the particle systems.
 The .ps file can be given as a specific string, e.g. "ps_bubbles.ps", or it can be a list or array or strings. If a list or array is given, the .ps file that spawns will be chosen at random from the list or array.
 In order to place a particle system at an arbitrary location, a temp entity is used, using the default temp entity name. If the maximum number of temp entities already exist, some will be recycled in the new position on the spline. SpawnParticlesOnSpline returns true if any temp entities were recycled, or false if only new entities were used created.
 If a specific name is given using the asEntityBaseName argument, then it will be used instead. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If the names of the temp entities are needed to refer to them later, for example to update the particles on the spline, use a specific string for asEntityBaseName. SpawnParticlesOnSpline returns true is any entities were recycled, or false if all the entities are newly created.
 afPhase is optional. It can be used to adjust the spread of the entities on the curve with a number between 0.0f and 1.0f, or it can be omitted. If it is omitted or if it is given as any number less than zero, then the default spacing will be used. The default spacing is the "full spread" - that is to say the first entity will be spawned at the start of the curve, the last at the end, and all the others evenly in between. However, if value between 0.0f and 1.0f is used for afPhase, then the entities will be spawned within their own division of the curve, with the phase 0.0f - 1.0f specifying how far through that division it will appear.
 The following diagram illustrates the phase option:
<syntaxhighlight>
|1----2----3----4| <- default spacing: no phase, full spread.
|1---2---3---4---| <- phase = 0.0f, each object at the start of its division.
|-1---2---3---4--| <- phase = 0.25f, each object 1/4 of the way through its division.
|--1---2---3---4-| <- phase = 0.5f, each object 1/2 of the way through its division.
|---1---2---3---4| <- phase = 0.75f, each object 3/4 of the way through its division.
|1---2---3---4---| <- phase = 1.0f is the same as phase = 0.0f.
</syntaxhighlight>
 If a particle system already exists with the given name, then it will be destroyed and replaced.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asPSFile, cListString@ ahPSFileList, string[] asPSFileArray'' - A string, an array of strings, or a list of strings containing one or more .ps files.
#''uint aulQty'' - The number of entities to be placed on the spline.
#''cSpline@ ahSpline'' - A spline to place entities on.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline("WigglyPathFlame", "ps_fire_candle.ps", 10, vBigWigglyPath);
// 10x ps_fire_candle.ps have been spawned on the existing spline curve vBigWigglyPath.

// Example 2:
Spawner.SpawnEntitiesOnSpline("ps_fire_candle.ps", 16, cSpline(cVector(2.0f, 2.0f, 10.0f), cVector(4.0f, 2.0f, 10.0f)));
// 16x flames have been spawned in a line shape.
// The line is formed from a new anonymous cSpline defined by two cVectors.
// The temp entities have not been named, so they cannot be updated and may be recycled.

// Example 3:
cSpline vFloatyFlameArch = cSpline(cVector(2.0f, 0.0f, 10.0f), cVector(2.0f, 3.0f, 10.0f), cVector(4.0f, 3.0f, 10.0f), cVector(4.0f, 0.0f, 10.0f));

cListString listFlameTypes;
listFlameTypes.Add("ps_fire_candle.ps");
listFlameTypes.Add("ps_fire_candle_red.ps");
listFlameTypes.Add("ps_fire_candle_blue.ps");

Spawner.SpawnEntitiesOnSpline("FloatyFlame", listFlameTypes, 16, vFloatyFlameArch, 0.5f);
// 16x flames have been spawned in an arch shape, where each sits halfway through own 16th division (phase = 0.5f).
// The arch shape is provided by an existing named cSpline, defined by four cVectors, making a cubic bezier.
// Each particle system was selected at random from one of three .ps files.
// Since the cSpline and the carrier entities have been named ("FloatyFlame_0", "FloatyFlame_1" etc.) they can be referred to and updated later.
</syntaxhighlight>

===Movement and rotation===

====SetSpawnArea()====
<syntaxhighlight lang="cpp">
void SetSpawnArea(string asSpawnArea)
void SetSpawnArea(string[] asSpawnAreaArray)
void SetSpawnArea(cListString asSpawnAreaList)
</syntaxhighlight>
The simplest way to allocate a specific Spawn Area is with the SpawnArea property. (<code>Spawner.SpawnArea = "someArea";</code>)
 However, the SetSpawnArea() method can also be used to specify multiple Script Areas with an array or list. If multiple Script Areas are specified then one of them will be selected at random for each item spawned.
 This has only one advantage: spawned items take on the rotation of their Spawn Area.
 If the desired outcome is to [[HPL2/HPL2_Helper_Scripts/Spawner#Spawning_with_rotation|spawn objects with random rotation]], the only way to achieve this through script to create a handful of Areas with various rotations, assign them all the SetSpawnArea(), and then each spawned item will take on the rotation of one of the areas.
#''string asSpawnArea, string[] asSpawnAreaArray, cListString, asSpawnAreaList'' - One or more names to be designated as the spawn area.
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SetSpawnArea("MyScriptArea");
Spawner.SpawnEntitiesInBox("Hammer", "hammer.ent", 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24x hammer.ent will be spawned in the defined bos.

// Example 2:
string[] sAreas = { "MyScriptArea1", "MyScriptArea2", "MyScriptArea3", "MyScriptArea4" };
Spawner.SetSpawnArea(sAreas);
Spawner.SpawnEntitiesInBox("Hammer", "hammer.ent", 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24x hammer.ent will be spawned in the defined box, each with the rotation copied from one of the 4 script areas.
</syntaxhighlight>

====UpdateEntitiesOnSpline()====
<syntaxhighlight lang="cpp">
bool UpdateEntitiesOnSpline(string asEntityBaseName, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
If SpawnEntitiesOnSpline() or SpawnParticlesOnSpline() has been used with a specific asEntityBaseName, and if the spline position has changed or a new phase value is desired, then UpdateEntitiesOnSpline() can be used to update the entities' or particles' positions, without recycling or further spawning.
 UpdateEntitiesOnSpline returns false if any of the expected entities do not exist, or true if the were all found and updated successfully.
 If a unique asEntityBaseName was not used, this may have enexpected results.
#''string asEntityBaseName'' - The base name used to previously spawn items on the spline.
#''uint aulQty'' - The number of items that were previously spawned in the spline.
#''cSpline ahSpline'' - A reference to an existing spline.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline(vBigWigglyPath, 10, "chair.ent", "WigglyPathChair");
// 10x chair.ent have been spawned on the curve vBigWigglyPath.
// ...some time later... vBigWigglyPath has been updated with new vectors:
Spawner.UpdateEntitiesOnSpline(vBigWigglyPath, 10, "WigglyPathChair");
// The 10 entities have adjusted to the new curve vectors.

// Example 2:
OnEnter()
{
float fWigglyPathPhase = 0.0f;
Spawner.SpawnEntitiesOnSpline(vBigWigglyPath, 1, "chair.ent", "WigglyPathChair", fWigglyPathPhase);
}

OnUpdate(float asStep)
{
fWigglyPathPhase = Math.Wrap(fWigglyPathPhase + afStep / 5.0f);
Spawner.UpdateEntitiesOnSpline(vBigWigglyPath, 1, "WigglyPathChair", fWigglyPathPhase);
}
// In this example, a single chair.ent is spawned on a curve name vBigWigglyPath when the level is first entered.
// fWigglyPathPhase updates between 0.0f and 1.0f over the course of 5 seconds (see Math.Wrap()) and UpdateEntitiesOnSpline() applies the new phase.
// The result is that the chair continuous moves along the curve vBigWigglyPath every 5 seconds, then loops back to the start.
</syntaxhighlight>

__FORCETOC__

HPL2/HPL2 Helper Scripts/Spawner

2023-12-22T23:21:34Z

Mrbehemo:

{{TocRight}}
This page documents "HelperScripts_Spawner.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].

=Summary=
The script class cSpawner provides methods for spawning entities and particle systems at specific vector positions.

===Spawn area===
The normal global functions provided by HPL2 only allow scripts to place objects at an existing Script Area. Spawner makes use of this and teleports the objects into the desired position afterwards.

There are three options for using Spawner, regarding a Spawn Area:
# Simply add a Script Area to the level named "SpawnArea", anywhere, any size.
# Tell Spawner to use a Script Area that already exists in the map, anywhere, any size, regardless of any other purpose.
# Tell Spawner to use multiple Script Areas placed in the map especially. This is only useful for semi-random rotation.

The default named Area is "SpawnArea" - you can change this using the SpawnArea property in script.
<syntaxhighlight lang="cpp">
Spawner.SpawnArea = "SomeOtherArea";
</syntaxhighlight>
Whatever it is called, there must be designated Script Area in the map, ''somewhere'', whose name matches SpawnArea. It doesn't matter what size it is or where it is located, as long as it exists.

===Spawning with shapes===
As well as spawning enties at specific positions, Spawner can also spawn entities randomly within a box or sphere shape, or spread evenly along a curve. It can also spawn particle systems at specific places or on a curve.

===Spawning with rotation===
It isn't possible to set the world rotation of an entity through script alone. However, spawned items will match the rotation of the whatever Script Area they were spawned at.

The SpawnArea propery allows one specific area to be set, but the [[HPL2/HPL2_Helper_Scripts/Spawner#SetSpawnArea.28.29|SetSpawnArea()]] ''method'' will accept an array or list of area names. When more than one Spawn Area is set, each spawned item will choose a different one at random. Having multiple Spawn Areas has no advantage other than having multiple sources for rotation.

For example, if the desired outcome is to spawn many debris objects with random-ish rotations, multiple Script Areas should be created in the level and given specific names and different rotations. It doesn't matter what size or location they are, only their rotation matters. In script, they should all be assigned with [[HPL2/HPL2_Helper_Scripts/Spawner#SetSpawnArea.28.29|SetSpawnArea()]], and then each spawned item will take on the rotation of one of the areas at random.

===Particles & temporary entities===
In order to spawn particle systems, Spawner spawns a "temp entity" - an invisible entity that the particle system is attached to. The number of temp entities is limited (256 by default) and when the full number is reached, older ones will be recycled.

If Spawner is used to create entities without specifying a name for them, they will be treated like temp entities too.

The entity file used for temp entities is called "SpawnerTemp.ent" and is located in the ""HPL2HelperScripts" folders. This can be changed using the TempEntityFile property, if required for some reason.

===Save data===
Spawner does not save any data of its own. By default, entities created by Spawner will be saved along with the save game and Spawner will have no need to remember them on the next play session. The SaveEntities property can be used to change this behaviour at run-time. Its default is true.
<syntaxhighlight lang="cpp">
Spawner.SpawnEntityAtPos("ent1", "spookyChair.ent", cVector(0.0f, 0.0f, 0.0f)); // This new entity will save by *default*.
Spawner.SaveEntities = false;
Spawner.SpawnEntityAtPos("ent2", "spookyTable.ent", cVector(2.0f, 0.0f, 0.0f)); // This new entity will *not* save, specifically.
Spawner.SaveEntities = true;
Spawner.SpawnEntityAtPos("ent3", "spookyCrate.ent", cVector(4.0f, 0.0f, 0.0f)); // This new entity *will* save, specifically.
</syntaxhighlight>

===Advanced info===
'''Advanced users''' may wish to examine "HelperScripts_Spawner.hps" to see how it makes use of other script classes. There are also some private variables that could to tweaked to fit the needs of a specific project, such as the default names for entities and the maximum number of temp entities allowed.

=Spawner=
Spawner is the name of the object that manages spawning entities at specific map locations.

==Behaviours==
"HelperScripts_Spawner.hps" declares an object called '''Spawner''', of the new script class cSpawner. To access its methods, just use "Spawner." followed by the function call. E.g.:
<syntaxhighlight lang="cpp">
Spawner.SpawnEntityAtPos("bigThing", "bigThing.ent", cVector(1.1f, 2.2f, 3.3f));
</syntaxhighlight>

==Properties==
Spawner provides the following properties:

====SaveEntities====
<syntaxhighlight lang="cpp">
string SaveEntities
</syntaxhighlight>
The bool property SaveEntities can be used to specify whether entities and particle systems spawned by Spawner will be saved as part of the save game. (Default = true)
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntityAtPos("ent1", "spookyChair.ent", cVector(0.0f, 0.0f, 0.0f)); // This new entity will save by default.
Spawner.SaveEntities = false;
Spawner.SpawnEntityAtPos("ent2", "spookyTable.ent", cVector(2.0f, 0.0f, 0.0f)); // This new entity will ''not'' save, specifically.
Spawner.SaveEntities = true;
Spawner.SpawnEntityAtPos("ent3", "spookyCrate.ent", cVector(4.0f, 0.0f, 0.0f)); // This new entity ''will'' save, specifically.
</syntaxhighlight>

====SpawnArea====
<syntaxhighlight lang="cpp">
string SpawnArea
</syntaxhighlight>
The string property SpawnArea can get or set the named Script Area used for spawning entities. (Default = "SpawnArea")
 (The advantage of using the SpawnArea property is that it can just be set to any Script Area that happens to exist in the map.)
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnArea = "LibraryEntranceTriggerB";
// Spawner will use the Script Area named "LibraryEntranceTriggerB" instead of the default name.
</syntaxhighlight>

====TempEntityBaseName====
<syntaxhighlight lang="cpp">
string TempEntityBaseName
</syntaxhighlight>
The string property TempEntityBaseName can get or set the prefix used when naming temp entities. (Default = "SpawnerTemp")
 If TempEntityBaseName is "SpawnerTemp" then temp entities will have names like "SpawnerTemp_0", "SpawnerTemp_1", etc..
 Note: This can only be changed before Spawner has actually spawned any temp entities, otherwise it would not be able to update or recycle them.
<syntaxhighlight lang="cpp">
// Example:
Spawner.TempEntityBaseName = "MySpecialEntityName";
// Spawner will now create temporary entities with names like "MySpecialEntityName_0", "MySpecialEntityName_1", etc..
</syntaxhighlight>

====TempEntityFile====
<syntaxhighlight lang="cpp">
string TempEntityFile
</syntaxhighlight>
The string property TempEntityFile can get or set the .ent file used for spawning temporary entities for particle systems. (Default = "SpawnerTemp.ent")
 The only reason to change TempEntityFile is if there is a specific entity that should be used instead.
 Note: This can only be changed before Spawner has actually spawned any temp entities, otherwise it would not be able to update or recycle them.
<syntaxhighlight lang="cpp">
// Example:
Spawner.TempEntityFile = "CustomTempEnt.ent";
// Spawner will attempt to spawn temp entities from the file "CustomTempEnt.ent" instead of the default file.
</syntaxhighlight>

==Methods==
Spawner provides the following methods:

===Spawning entities===

====SpawnEntityAtPos()====
<syntaxhighlight lang="cpp">
bool SpawnEntityAtPos(string asNewEntityName, string asEntityFile, cVector avPosition)
bool SpawnEntityAtPos(string asNewEntityName, cListString@ ahEntityFileList, cVector avPosition)
bool SpawnEntityAtPos(string asNewEntityName, string[] asEntityFileArray, cVector avPosition)
</syntaxhighlight>
Spawns an entity at a specific vector position. If an entity with that name already exists, it will be recycled. That is, it will be teleported into the new position. SpawnEntityAtPos returns true if the entity was recycled, or false if a new entity was created.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
#''string asNewEntityName'' - The name that the new entity will be given. Should either be unique, or an existing entity will be recycled instead.
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''cVector avPosition'' - A 3d vector position in the map to spawn the entity.
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntityAtPos("AcmeAnvil", "anvil.ent", Math.GetPlayerPosVec() + cVector(0.0f, 3.0f, 0.0f))
// An entity of the type "anvil.ent" spawns 3m above the player's location.
</syntaxhighlight>

====SpawnEntitiesInBox()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cVector avBoxMin, cVector avBoxMax)
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cVector avBoxMin, cVector avBoxMax)
bool SpawnEntitiesInBox(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cVector avBoxMin, cVector avBoxMax)
</syntaxhighlight>
Spawns a quantity of entities a random positions within a box shape defined by a pair of vectors (similar to the box shaped starting position in the particle editor). If the box is sized zero in one dimension then that is effectively a rectangle, so this can also be used spawn objects on a plane.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If the script needs to refer to the entities by name later, use asEntityBaseName to give them specific names.
 SpawnEntitiesInBox returns true if any entities were recycled, or false if all the entities are newly created.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to spawn in the box.
#''cVector avBoxMin'' - The minimum extent of the box.
#''cVector avBoxMax'' - The maximum extent of the box.
<syntaxhighlight lang="cpp">
// Example:
cListString listJunkProps;
listJunkProps.Add("wooden_board02.ent");
listJunkProps.Add("tongs.ent");
listJunkProps.Add("hammer.ent");
listJunkProps.Add("chisel.ent");
listJunkProps.Add("basket.ent");
listJunkProps.Add("flask01.ent");
listJunkProps.Add("dungeon_small01.ent");
listJunkProps.Add("brick.ent");
listJunkProps.Add("brick.ent");
listJunkProps.Add("brick.ent");

Spawner.SpawnEntitiesInBox("Junk_A", listJunkProps, 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24 random junk items are selected from the list and spawned in a square, with names "Junk_A_0" to "Junk_A_23".
// Note that "brick.ent" is three times more likely to spawn than the others.
</syntaxhighlight>

====SpawnEntitiesInSphere()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cVector avOrigin, float afRadius)
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cVector avOrigin, float afRadius)
bool SpawnEntitiesInSphere(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cVector avOrigin, float afRadius)
</syntaxhighlight>
Spawns a quantity of entities a random positions within a sphere shape defined by a centre vector and a radius.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If you need to know the names of the entities to refer to them later, use asEntityBaseName.
 SpawnEntitiesInSphere returns true if any entities were recycled, or false if all the entities are newly created.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to spawn in the sphere.
#''cVector avOrigin'' - The centre of the sphere.
#''cVector afRadius'' - The radius of the sphere.
<syntaxhighlight lang="cpp">
// Example:
Spawner.SpawnEntitiesInSphere("MegaOrb", "orb.ent", 1000, Math.GetPlayerPosVec(), 4.0f);
SetPlayerSanity(0.0f);
// One thousand orbs have spawned around the player, placing them at the centre of an 8m wide MegaOrb. The player had no chance to remain sane in such circumstances.
// Note: if no string was given for asEntityBaseName, then the number of entities spawned would be limited to the temp entity max (default = 256).
</syntaxhighlight>

====SpawnEntitiesOnSpline()====
<syntaxhighlight lang="cpp">
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", string asEntityFile, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", cListString ahEntityFileList, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnEntitiesOnSpline(string asEntityBaseName = "SpawnerTemp", string[] asEntityFileArray, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
Spawns a quantity of entites evenly spaced along a spline.
 The .ent file can be given as a specific string, e.g. "orb.ent", or it can be a list or array or strings. If a list or array is given, the .ent file that spawns will be chosen at random from the list or array.
 If asEntityBaseName is given, it will be used to name the new entities. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If asEntityBaseName is omitted, then temp entity names will be used instead. If an entity with that name already exists, it will be recycled, that is it will be teleported into the new position. If the names of the entities are needed to refer to them later or update their position, use asEntityBaseName.
 SpawnEntitiesOnSpline returns true if any entities were recycled, or false if all the entities are newly created.
 afPhase is optional. It can be used to adjust the spread of the entities on the curve with a number between 0.0f and 1.0f, or it can be omitted. If it is omitted, or less than zero, then the default spacing will be used.
 The default spacing is the "full spread" - that is to say the first entity will be spawned at the start of the curve, the last entity at the very end, and all the others evenly in between.
 However, if value between 0.0f and 1.0f is used for afPhase, then the entities will be spawned within their own division of the curve, with the phase 0.0f - 1.0f specifying how far through that division it will appear.
 The following diagram illustrates the phase option:
<syntaxhighlight>
|1----2----3----4| <- default spacing: no phase, full spread.
|1---2---3---4---| <- phase = 0.0f, each object at the start of its division.
|-1---2---3---4--| <- phase = 0.25f, each object 1/4 of the way through its division.
|--1---2---3---4-| <- phase = 0.5f, each object 1/2 of the way through its division.
|---1---2---3---4| <- phase = 0.75f, each object 3/4 of the way through its division.
|1---2---3---4---| <- phase = 1.0f is the same as phase = 0.0f.
</syntaxhighlight>
 To update the position of the spawned entities without respawning them, for example if the spline or phase has changed, see UpdateEntitiesOnSpline().
 You can easily use SpawnEntitiesOnSpline() with a single Bezier or a straight line between two points, depending on how you construct your spline. See the examples, or see cSpline and cBezier classes for more information.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asEntityFile, cListString@ ahEntityFileList, string[] asEntityFileArray'' - A string, an array of strings, or a list of strings containing one or more .ent files.
#''uint aulQty'' - The number of entities to be placed on the spline.
#''cSpline@ ahSpline'' - A spline to place entities on.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline("WigglyPathChair", "chair.ent", 10, vBigWigglyPath);
// 10x chair.ent have been spawned on the existing spline curve vBigWigglyPath.

// Example 2:
SpawnEntitiesOnSpline("rock.ent", 16, cSpline(cVector(2.0f, 2.0f, 10.0f), cVector(4.0f, 2.0f, 10.0f));
// 16x rock.ent have been spawned in a line shape.
// The line is formed from a new cSpline defined by two cVectors.
// The entities were not named, so temp entity names have been used. This means that they cannot be updated and may be recycled.

// Example 3:
cSpline vFloatyRockArch = cSpline(cVector(2.0f, 0.0f, 10.0f), cVector(2.0f, 3.0f, 10.0f), cVector(4.0f, 3.0f, 10.0f), cVector(4.0f, 0.0f, 10.0f));

cListString listRockTypes;
for (uint i = 0; i < 5; i++) listRockTypes.Add("rock_" + i + ".ent");

Spawner.SpawnEntitiesOnSpline("FloatyRockArchEnt", listRockTypes, 16, vFloatyRockArch);
// 16x rocks have been spawned in an arch shape.
// The arch is formed from a new cSpline defined by four cVectors, making a cubic bezier.
// Each rock entity was selected at random from one of five created in the list.
</syntaxhighlight>

===Spawning particles===

====SpawnParticlesAtPos()====
<syntaxhighlight lang="cpp">
bool SpawnParticlesAtPos(string asNewPSName, string asPSFile, cVector avPosition)
bool SpawnParticlesAtPos(string asNewPSName, cListString@ ahPSFileList, cVector avPosition)
bool SpawnParticlesAtPos(string asNewPSName, string[] asPSFileArray, cVector avPosition)
</syntaxhighlight>
Spawns a particle system at a specific vector position.
 The .ps file can be given as a specific string, e.g. "ps_bubbles.ps", or it can be a list or array or strings. If a list or array is given, the .ps file that spawns will be chosen at random from the list or array.
 In order to place a particle system at an arbitrary location, a temp entity is used, using the msTempEntNameBase. If the maximum number of temp entities already exist, one will be recycled in the new position. SpawnParticlesAtPos returns true if the temp entity was recycled, or false if a new entity was created.
 If a particle system already exists with the given name, then it will be destroyed and replaced.
#''string asNewPSName'' - The name that the new particle system will be given. Should either be unique, or an existing system will be recycled instead.
#''string asPSFile, cListString@ ahPSFileList, string[] asPSFileArray'' - A string, an array of strings, or a list of strings containing one or more .ps files.
#''cVector avPosition'' - A 3d vector position in the map to spawn the entity.
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnParticlesAtPos("FloatyFlame", "ps_fire_candle.ps", cVector(23.0f, 2.25f, 14.5f));
// A candle flame will be spawned at the given vector position, using a temp entity.

// Example 2:
string[] arrayFlameTypes = { "ps_fire_candle.ps", "ps_fire_candle_red.ps", "ps_fire_candle_blue.ps" };

Spawner.SpawnParticlesAtPos("FloatyFlame", listFlameTypes, cVector(23.0f, 2.25f, 14.5f));
// A candle flame will be spawned at the given vector position, using a temp entity.
// The .ps file will be selected at random from the array.
</syntaxhighlight>

====SpawnParticlesOnSpline()====
<syntaxhighlight lang="cpp">
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", string asPSFile, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", cListString ahPSFileList, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
bool SpawnParticlesOnSpline(string asEntityBaseName = "SpawnerTemp", string[] ahPSFileArray, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
Spawns a quantity of particle systems evenly spaced along a spline. The ahSpline argument should refer to an existing cSpline variable if the positions of the particles should need to be updated later. See the examples, or see cSpline for further information on creating splines. To update the position of the spawned entities without respawning them, for example if the spline or phase has changed, see UpdateEntitiesOnSpline(). This will also move the particle systems.
 The .ps file can be given as a specific string, e.g. "ps_bubbles.ps", or it can be a list or array or strings. If a list or array is given, the .ps file that spawns will be chosen at random from the list or array.
 In order to place a particle system at an arbitrary location, a temp entity is used, using the default temp entity name. If the maximum number of temp entities already exist, some will be recycled in the new position on the spline. SpawnParticlesOnSpline returns true if any temp entities were recycled, or false if only new entities were used created.
 If a specific name is given using the asEntityBaseName argument, then it will be used instead. E.g. if asEntityBaseName = "box", then new entities will be named like "box_0", "box_1" etc.. If the names of the temp entities are needed to refer to them later, for example to update the particles on the spline, use a specific string for asEntityBaseName. SpawnParticlesOnSpline returns true is any entities were recycled, or false if all the entities are newly created.
 afPhase is optional. It can be used to adjust the spread of the entities on the curve with a number between 0.0f and 1.0f, or it can be omitted. If it is omitted or if it is given as any number less than zero, then the default spacing will be used. The default spacing is the "full spread" - that is to say the first entity will be spawned at the start of the curve, the last at the end, and all the others evenly in between. However, if value between 0.0f and 1.0f is used for afPhase, then the entities will be spawned within their own division of the curve, with the phase 0.0f - 1.0f specifying how far through that division it will appear.
 The following diagram illustrates the phase option:
<syntaxhighlight>
|1----2----3----4| <- default spacing: no phase, full spread.
|1---2---3---4---| <- phase = 0.0f, each object at the start of its division.
|-1---2---3---4--| <- phase = 0.25f, each object 1/4 of the way through its division.
|--1---2---3---4-| <- phase = 0.5f, each object 1/2 of the way through its division.
|---1---2---3---4| <- phase = 0.75f, each object 3/4 of the way through its division.
|1---2---3---4---| <- phase = 1.0f is the same as phase = 0.0f.
</syntaxhighlight>
 If a particle system already exists with the given name, then it will be destroyed and replaced.
#''string asEntityBaseName'' - The name to use for the new entities, which will be appended with "_0", "_1" etc. (Optional, default = "SpawnerTemp")
#''string asPSFile, cListString@ ahPSFileList, string[] asPSFileArray'' - A string, an array of strings, or a list of strings containing one or more .ps files.
#''uint aulQty'' - The number of entities to be placed on the spline.
#''cSpline@ ahSpline'' - A spline to place entities on.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline("WigglyPathFlame", "ps_fire_candle.ps", 10, vBigWigglyPath);
// 10x ps_fire_candle.ps have been spawned on the existing spline curve vBigWigglyPath.

// Example 2:
Spawner.SpawnEntitiesOnSpline("ps_fire_candle.ps", 16, cSpline(cVector(2.0f, 2.0f, 10.0f), cVector(4.0f, 2.0f, 10.0f)));
// 16x flames have been spawned in a line shape.
// The line is formed from a new anonymous cSpline defined by two cVectors.
// The temp entities have not been named, so they cannot be updated and may be recycled.

// Example 3:
cSpline vFloatyFlameArch = cSpline(cVector(2.0f, 0.0f, 10.0f), cVector(2.0f, 3.0f, 10.0f), cVector(4.0f, 3.0f, 10.0f), cVector(4.0f, 0.0f, 10.0f));

cListString listFlameTypes;
listFlameTypes.Add("ps_fire_candle.ps");
listFlameTypes.Add("ps_fire_candle_red.ps");
listFlameTypes.Add("ps_fire_candle_blue.ps");

Spawner.SpawnEntitiesOnSpline("FloatyFlame", listFlameTypes, 16, vFloatyFlameArch, 0.5f);
// 16x flames have been spawned in an arch shape, where each sits halfway through own 16th division (phase = 0.5f).
// The arch shape is provided by an existing named cSpline, defined by four cVectors, making a cubic bezier.
// Each particle system was selected at random from one of three .ps files.
// Since the cSpline and the carrier entities have been named ("FloatyFlame_0", "FloatyFlame_1" etc.) they can be referred to and updated later.
</syntaxhighlight>

===Movement and rotation===

====SetSpawnArea()====
<syntaxhighlight lang="cpp">
void SetSpawnArea(string asSpawnArea)
void SetSpawnArea(string[] asSpawnAreaArray)
void SetSpawnArea(cListString asSpawnAreaList)
</syntaxhighlight>
The simplest way to allocate a specific Spawn Area is with the SpawnArea property. (<code>Spawner.SpawnArea = "someArea";</code>)
 However, the SetSpawnArea() method can also be used to specify multiple Script Areas with an array or list. If multiple Script Areas are specified then one of them will be selected at random for each item spawned.
 This has only one advantage: spawned items take on the rotation of their Spawn Area.
 If the desired outcome is to [[HPL2/HPL2_Helper_Scripts/Spawner#Spawning_with_rotation|spawn objects with random rotation]], the only way to achieve this through script to create a handful of Areas with various rotations, assign them all the SetSpawnArea(), and then each spawned item will take on the rotation of one of the areas.
#''string asSpawnArea, string[] asSpawnAreaArray, cListString, asSpawnAreaList'' - One or more names to be designated as the spawn area.
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SetSpawnArea("MyScriptArea");
Spawner.SpawnEntitiesInBox("Hammer", "hammer.ent", 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24x hammer.ent will be spawned in the defined bos.

// Example 2:
string[] sAreas = { "MyScriptArea1", "MyScriptArea2", "MyScriptArea3", "MyScriptArea4" };
Spawner.SetSpawnArea(sAreas);
Spawner.SpawnEntitiesInBox("Hammer", "hammer.ent", 24, cVector(10.0f, 0.25f, 15.0f), cVector(15.0f, 0.25f, 20.0f));
// 24x hammer.ent will be spawned in the defined box, each with the rotation copied from one of the 4 script areas.
</syntaxhighlight>

====UpdateEntitiesOnSpline()====
<syntaxhighlight lang="cpp">
bool UpdateEntitiesOnSpline(string asEntityBaseName, uint aulQty, cSpline ahSpline, float afPhase = -1.0f)
</syntaxhighlight>
If SpawnEntitiesOnSpline() or SpawnParticlesOnSpline() has been used with a specific asEntityBaseName, and if the spline position has changed or a new phase value is desired, then UpdateEntitiesOnSpline() can be used to update the entities' or particles' positions, without recycling or further spawning.
 UpdateEntitiesOnSpline returns false if any of the expected entities do not exist, or true if the were all found and updated successfully.
 If a unique asEntityBaseName was not used, this may have enexpected results.
#''string asEntityBaseName'' - The base name used to previously spawn items on the spline.
#''uint aulQty'' - The number of items that were previously spawned in the spline.
#''cSpline ahSpline'' - A reference to an existing spline.
#''float afPhase'' - An adjustment to the spread of the entities, 0.0f - 1.0f, or -1.0f for full spread. (Optional, default = -1.0f)
<syntaxhighlight lang="cpp">
// Example 1:
Spawner.SpawnEntitiesOnSpline(vBigWigglyPath, 10, "chair.ent", "WigglyPathChair");
// 10x chair.ent have been spawned on the curve vBigWigglyPath.
// ...some time later... vBigWigglyPath has been updated with new vectors:
Spawner.UpdateEntitiesOnSpline(vBigWigglyPath, 10, "WigglyPathChair");
// The 10 entities have adjusted to the new curve vectors.

// Example 2:
OnEnter()
{
float fWigglyPathPhase = 0.0f;
Spawner.SpawnEntitiesOnSpline(vBigWigglyPath, 1, "chair.ent", "WigglyPathChair", fWigglyPathPhase);
}

OnUpdate(float asStep)
{
fWigglyPathPhase = Math.Wrap(fWigglyPathPhase + afStep / 5.0f);
Spawner.UpdateEntitiesOnSpline(vBigWigglyPath, 1, "WigglyPathChair", fWigglyPathPhase);
}
// In this example, a single chair.ent is spawned on a curve name vBigWigglyPath when the level is first entered.
// fWigglyPathPhase updates between 0.0f and 1.0f over the course of 5 seconds (see Math.Wrap()) and UpdateEntitiesOnSpline() applies the new phase.
// The result is that the chair continuous moves along the curve vBigWigglyPath every 5 seconds, then loops back to the start.
</syntaxhighlight>

__FORCETOC__