Frictional Wiki - User contributions [en]

HPL2/TDD/Entity Types

2026-02-07T20:19:24Z

BoxFigs: /* Push */

{{TocRight}}

This page lists the different types of entities found within the HPL2 engine. The type determines how the entity will be set up, what kind it is, what it does under different circumstances etc. Using the Model Editor you can identify and specify which type an entity has and its type vars, in Settings > User defined variables. In the Level Editor, the different types have different settings applicable for them, known as instance vars. For example, a MoveObject type will have the OffsetArea box available in the Level Editor, and an Item (Note) type will have a NoteText box available.

A list of all the types and subtypes can be found in the table of contents to the right.

== StaticProp ==

A StaticProp entity resembles a static object. They have no available type properties, but they can still use physics bodies (collision boxes) and have mass/gravity. Note that they cannot be interacted with in the game, and cannot be disabled. If you need this feature, use Object (Static) instead.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CastShadows || Bool || true || If entity casts shadows.
|-
| IsAffectedByDecal || Bool || true || If decals can be created on entity.
|-
|}

== CommentaryIcon ==

A CommentaryIcon entity is simply an object that can execute commentary sound files, as it was done in the main game. These only appear if the player has "Commentary" enabled in their settings.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| RotateSubMesh || String || || The name of the submesh that is to be rotated
|-
|}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| File || File (.comment) || || The .comment file for the commentary.
|-
|}

== Object ==

Objects are entities that can be activated/deactivated, broken, and interact with physics.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| BreakActive || Bool || false || If entity is broken when hit hard enough or health is 0.
|-
| BreakDestroyJoints || Bool || false || If all physics joints should be destroyed when broken.
|-
| BreakMinEnergy || Float || 100 || The minimum energy needed for breakage. Energy = Object1Speed * Object1Mass + Object2Speed * Object2Mass. Speed = m/s. If Object 2 is floor or something static, its speed is always 0 and does not contribute to total energy!
|-
| BreakEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| BreakEntityAlignBody || String || || The body BreakEntity uses to align itself when created. No entity is created if left empty.
|-
| BreakSound || File (.snt) || || The sound made when broken.
|-
| BreakParticleSystem || File (.ps) || || Particle system shown when broken.
|-
| BreakImpulse || Float || 4 || Impulse (speed in m/s really) added to all bodies in BreakEntity when created. The direction of impulse is outwards from center of entity.
|-
| HitDamageAmount || Float || 5 || The amount of damage made when hitting an enemy or player.
|-
| HitDamageStrength || Int || 1 || The strength of the damage.
|-
| MinHitDamageSpeed || Float || 3 || The minimum speed (m/s) needed for damage to be made.
|-
| LifeLength || Float || 0 || A time after which the entity automatically breaks. 0=lasts forever.
|-
| IsFood || Bool || false || If this is food for some enemies and can be used to lure them. Needs to have break active and health determines how long the food lasts. Waterlurkers are the only enemy type that is lured by and eats food objects.
|-
| ShowHints || Bool || true || If a hint can be triggered by interacting with the prop.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| ContainedItem || String || None || An item that is created when entity breaks. Must match an entity file name (extension .ent optional) in the "items" folder.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
| IsInsanityVision || Bool || false || If the prop is only shown when insanity is low enough.
|-
| VisionMaxSanity || Float || 30 || The max sanity the player can have for prop to show if it is an insanity vision. The object will only be visible if the player's sanity is less than this value.
|-
|}

=== Static ===

Not to be confused with an actual static object. This Object subtype is a generic object with common properties. The static subtype simply disables any additional properties from the other subtypes. An Object (Static) is similar in concept to a StaticProp type entity, however the Object (Static) can be deactivated, can break, has physics, and can have an interact callback set.

=== Grab ===

A Grab subtype is a normal Object entity with the ability to be grabbed by the player in the game. In order for this to work, the object must have a mass above 0.

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| GrabUseDepth || Bool || false || If GrabDepth is used. If not the interaction distance is used.
|-
| GrabDepth || Float || 1.5 || The distance which a grabbed object is automatically placed at.
|-
| GrabDepthInc || Float || 0.15 || Steps that the entity will move in when moving the mouse scroll.
|-
| GrabMinDepth || Float || 1.0 || Minimum distance the entity can be from player when grabbed.
|-
| GrabMaxDepth || Float || 2.2 || Maximum distance the entity can be from player when grabbed.
|-
| GrabUseOffset || Bool || false || If rotation and position offset is used. If not offset will be relative to the interact position.
|-
| GrabPositionOffset || Vector3f || 0 || Positional offset of entity.
|-
| GrabRotationOffset || Vector3f || 0 || Rotational offset of entity. It will automatically rotate to this when grabbed.
|-
| GrabThrowImpulse || Float || 10 || The speed (m/s) at which the entity is thrown.
|-
| GrabMassMul || Float || 0.1 || How much the object will weight when grabbed. Useful for heavier objects since they can wreck mayhem otherwise. 0.5% means half (50%) of the original weight.
|-
| GrabForceMul || Float || 1 || Change how much force is added to grabbed object.
|-
| GrabTorqueMul || Float || 1 || Change how much torque is added to grabbed object.
|-
| GrabUseRotation || Bool || true || If rotation should be used on grabbed object
|-
| GrabSkipNonOuterBodies || Bool || false || If true, then bodies that are inside a chain (has two or more joints attached to it) will not be grabbed.
|-
|}

=== Push ===

Similar to the Grab subtype, the Push subtype allows the player to push or drag the object by taking hold of it and walking or right clicking. Examples include large rocks and the bed covering the hole in the floor in the Prison - Southern Block.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| PushAtPoint || Bool || false || If the push force should be applied to the point at the object where interaction took place.
|-
| PushForceMul || Float || 1 || Multiplier for force applied. Used to fine tune interaction.
|-
| PushImpulse || Float || 2 || Impulse added when thrown.
|-
|}

=== Slide ===

A Slide Object is similar to the Grab subtype, except it can only be slid in a single direction for a certain amount. An existing (but unused) entity that uses this is the secret floor carpet you can slide to the side.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
|}

== SwingDoor ==

A SwingDoor entity is standard hinged door. Any door you can grab and swing open is considered a SwingDoor. To use a SwingDoor, you need to attach joints to where you want the door to swing around. These are usually placed by the hinges of the door. On the joint you can set the min and max values to limit how much the door can be opened. These are usually approximately 90 degrees apart in either positive or negative directions.

If the FullGameSave instance var is not enabled, SwingDoors will reset to their initial open amount when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the door is interacted with. Meaning that interacting with any part of the entity will work.
|-
| CloseOnSound || File (.snt) || || Sound played when the door is closed.
|-
| CloseOffSound || File (.snt) || || Sound played when the door is opened.
|-
| LockOnSound || File (.snt) || || Sound played when the door is locked.
|-
| LockOffSound || File (.snt) || || Sound played when the door is unlocked.
|-
| InteractLockedSound || File (.snt) || || Sound made when player interacts with a locked door.
|-
| Breakable || Bool || false || Can the door be broken.
|-
| DamageMesh1 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage1
|-
| DamageMesh2 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage2
|-
| BrokenEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| DamageSound || File (.snt) || || Sound made when a new damage mesh is used.
|-
| DamagePS || File (.ps) || || Particles created when a new damage mesh is used.
|-
| BreakSound || File (.snt) || || Sound made when broken.
|-
| BreakPS || File (.ps) || || Particles created when broken.
|-
| BreakImpulse || Float || 3 || Impulse set to objects in broken mesh. Incorrectly defined as a sound file in EntityTypes.cfg.
|-
| HealthDamage1 || Float || 66 || Health when damage mesh 1 is used.
|-
| HealthDamage2 || Float || 33 || Health when damage mesh 2 is used.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Locked || Bool || false || If the door is locked
|-
| OpenAmount || Float || 0 || The amount the door is open. 0 - 1.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
|}

== Lever ==

A Lever entity is an entity that can be swung between states to trigger callbacks. A lever requires a joint to swing around.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitSound || File (.snt) || || Sound played when at min limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MaxLimitSound || File (.snt) || || Sound played when at max limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MinLimitStuck || Bool || false || If the lever becomes stuck when reaching min. Missing from EntityTypes.cfg.
|-
| MaxLimitStuck || Bool || false || If the lever becomes stuck when reaching max. Missing from EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the position.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The initial stuck state for the lever. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

== Wheel ==

A Wheel entity is a wheel that can be turned. They use states similar to the levers. Some wheels can be turned indefinitely and some (mostly valves) can be turned for a fixed amount in order to trigger an event. Wheels require a joint.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the wheel is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
| MinLimitSound || File (.snt) || || Sound played at min limit
|-
| MaxLimitSound || File (.snt) || || Sound played at max limit
|-
| StuckSound || File (.snt) || || Sound played when stuck.
|-
| SlowDownRotation || Bool || true || If rotation should be slowed to 0 when not interacting.
|-
| SkipMiddleState || Bool || true || If the middle state (when not in max or min) should be skipped by script and connections.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
|}

== MultiSlider ==

A sliding-type lever that can be set to multiple states. Used for the gear levers in the Sewer.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
| NumOfStates || Int || 3 || The number of states used.
|-
| StickToStateMaxDist || Float || 0.1 || The distance from a state that the slider sticks.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| AutoMoveToCurrentState || Bool || true || If body should automove to current state when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the postion.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| ChangeStateSound || File (.snt) || || Sound played when state is changed Incorrectly defined as a string in EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| ChangeStateCallback || String || || Called when state changes Syntax: <code>void MyFunc(string &in asEntity, int alState)</code> Used instead of ConnectionStateChangeCallback, as this entity type can have more than two possible states.
|-
|}

== Lamp ==

A Lamp entity is a light source. If they are unlit, they can be lit by the player, consuming a tinderbox. Examples are torches and candles.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CanBeLitByPlayer || Bool || true || If the player can use a tinderbox on it to light it.
|-
| CanBeGrabbed || Bool || false || If it can be grabbed by the player. No effect. Presumably intended to make the entity behave like a Grab Object, yet this is unimplemented.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Lit || Bool || true || If the lamp is lit or not.
|-
| ConnectedLight || String || || Name of a light (that is not in an entity!) that will be connected to the this light and will increase/decrease in color as the lamp is turned on/off.
|-
| ConnectionLightAmount || Float || 1 || The amount to multiply the lamp's color by before adding it to the connected light's color.
|-
| ConnectionLightUseOnColor || Bool || true || If the on color should always be used. If false the light color (which might be flickering) is used.
|-
| ConnectionLightUseSpec || Bool || false || If the specular of the lamp color should be used.
|-
|}

== Button ==

A Button entity acts like a Lever, except it does not use a joint. It simply changes its connection state and toggles effects when interacted with.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| SwitchedOn || Bool || false || If the button starts as on or off
|-
| CanBeSwitchedOn || Bool || true || If player can switch it on.
|-
| CanBeSwitchedOff || Bool || false || If player can switch it off.
|-
|}

== Photocell ==

A prop that changes its texture illumination and connection state based on the light level around it. Presumably a leftover from Lux Tenebris, which featured light-based puzzles.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| LightLevelOnLimit || Float || 0.9 || Light level above this value turns the photocell on.
|-
| LightLevelOffLimit || Float || 0.1 || Light level below this value turns the photocell off.
|-
|}

== MoveObject ==

A MoveObject entity is an entity that can be specifically moved on a single axis through the use of scripting. It can be set to either Angular or Linear. Angular rotates the object around its own center point, unless otherwise specified by the use of an OffsetArea. Linear moves the object in a direction for a specified amount. Note that a linear move object can only move on one axis. You can pick X, Y, or Z in the entity and this cannot be changed mid-game. If you want the same object to move on more than 1 axis (for example left then forward) you can switch out the entity with an identical one that uses another axis. The script to move a MoveObject is <code>SetMoveObjectState</code> and <code>SetMoveObjectStateExt</code> (see [[HPL2/Engine Scripts|Engine Scripts]]).

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveObjectType || String || Linear || The way the object moves. Linear means position changes and Angular means rotation changes. Can be "Linear" or "Angular".
|-
| OpenAmount || Float || 1.0 || Linear: How much of the MoveAxis size that will mean that it is open. Angular: 1=90 degrees. 0.5=45deg and 2=180deg (any numbers inbetween are okay of course)
|-
| MoveAxis || String || X || he axis that the movement is about. For angular it is rotation axis and for linear it is the position axis that is changed. Can be "X", "Y", or "Z".
|-
| OpenAcc || Float || 5.0 || The acceleration for reaching OpenSpeed
|-
| OpenSpeed || Float || 1.0 || The goal speed when opening.
|-
| CloseAcc || Float || 5.0 || The acceleration for reaching CloseSpeed
|-
| CloseSpeed || Float || 1.0 || The goal speed when closing.
|-
| AutoMove || Bool || false || If the door should move towards some goal automatically.
|-
| AutoMoveStateGoal || Float || 0.0 || The amount (relative to the what is considered open) that it shall move towards.
|-
| AutoMoveAcc || Float || 9.0 || The acceleration when automoving
|-
| AutoMoveSpeed || Float || 5.0 || The goal speed when automoving
|-
| AutoMoveSlowdownDist || Float || 0.1 || The distance from state goal where it begins to slow down (in meters for linear and degrees for angular).
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| AngularOffsetArea || String || || When mode is angular, this the point it rotates around. If empty, it rotates around its center.
|-
|}

== Item ==

Item entities become inventory items when interacted with. They glow when in pickup range.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SubItemTypeName || String || || Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
| ImageFile || File (.tga/.dds/.jpg/.jpeg/.png) || || The icon shown in the inventory when picked up.
|-
| PickSound || String || Generic || The sound played when picked up. Must match a sound file name in the "ui" folder, starting with "pick_".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CustomSubItemTypeName || String || || If not emtpy it overrides SubItemTypeName in entity file. Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
|}

=== Puzzle ===

A Puzzle subtype item is a general item with no extra properties. Use this if you only need an inventory item to be used to trigger a scripted action. Other subtypes have special properties, but Puzzle only has the ability to be collected and used from the inventory. When used, it's loaded onto the crosshair so the player can use it on objects.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| TempVar || Float || 0 || User specfic usage.
|-
|}

=== Coins ===

Unused item type for the cut Thaler items. Thalers were once used to unlock Chests and use OilBarrels, with only the former functionality remaining.

{{warning|You can create custom coin items, but there is a single language entry which is hardcoded into the engine and can't be changed. This means that even if all the others are changed, looking at Chests will always say "Locked. Costs X Thalers to open."}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CoinAmount || Int || 10 || The amount of coins it contains.
|-
|}

=== Note ===

A Note item is an item that adds text to the player's journal. It displays itself when picked up. The note can be narrated, in which case it will automatically close once it's finished. If it isn't voiced, the player must close it. Use this if you want to make a Note item using a custom model or custom properties that differ from the main notes.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| NoteText || String || || The text and name of entry for note. Entry names for these are calculated: 'Note_'+NoteText+'_Name' and 'Note_'+NoteText+'_Text'
|-
| OpenNoteInJournal || Bool || true || If the journal should be opened when the note is picked up.
|-
| UseNarration || Bool || false || If the note has narration.
|-
|}

=== Diary ===

A Diary item is nearly identical to the Note item. Instead, it adds itself to the Diary section of the player's journal, whereas the Note adds itself to the Notes section. Additionally, diary entries are grouped together, so that when one is split into multiple parts, the player will always read them in order, regardless of the specific Diary items that were picked up.

Diaries are also always voice enabled, while Notes have the option for it. As such, a Diary without any voice files defined in its text will instantly close the journal on pickup.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DiaryText || String || || The text and name of entry for diary. Entry name for these calculated: 'Diary_'+DiaryText+'_Name'+Idx and 'Diary_'+DiaryText+'_Text'+Idx. Idx starts at 1.
|-
| DiaryCallback || String || || A special callback for diary pickup. Syntax: <code>void Func(string &in asItem, int lDiaryIdx)</code>. Call <code>ReturnOpenJournal(false)</code> to not open diary in journal after callback.
|-
|}

=== Lantern ===

A Lantern item can be picked up like a normal item, but is added as a lantern to the inventory. While having this item, the player can press F to toggle it, or click it in the inventory. Note: This is NOT the lantern model in the player's hands, only the item that gives it to the player. If you want a custom lantern model, you can follow [https://www.frictionalgames.com/forum/thread-12391.html this guide].

=== Health ===

A Health item acts like a health potion (Laudanum). When used, it increases the player's health by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much health is regained when used.
|-
|}

=== Sanity ===

A Sanity item acts like a sanity potion. When used, it increases the player's sanity by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much sanity is regained when used.
|-
|}

=== LampOil ===

A LampOil item acts like an oil potion. When used, it increases the player's lantern oil by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| OilAmount || Float || 25 || How much oil is regained when used.
|-
|}

=== Tinderbox ===

A Tinderbox item adds itself to the player's tinderbox counter in the inventory. Tinderboxes can be used once to light a light source.

=== HandObject ===

Unused. Would have equipped the corresponding hand object on use.

== Chest ==

This is an unused feature, but it was kept in the engine and can be restored by making a custom entity. It is a object which can be opened using coins (or their replacements, if a custom Coin-type entity is made). Interacting with it brings up a text GUI. The text GUI can be changed in the base language file.
To make an entity of this type, just copy an existing entity file and change its entity type.
'''The chests that ended up in the game are actually just Levers.'''

{{warning|In versions before 1.5, Chests did not write their CoinsNeeded instance var to save data, which caused the coin requirement of all Chests to default to 0 when loading a save.}}

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CoinsNeeded || Int || 200 || Coins required to open the chest.
|-
|}

== OilBarrel ==

An OilBarrel entity simply adds some oil to the player's lantern upon interaction. The oil amount depends on the player's combined total oil stored in their lantern and as LampOil type items (the sum of the oil that the items would refill on use), determined when the player first looks at the OilBarrel. If the total oil is less than 100, the OilBarrel will contain exactly enough oil to bring it to 100. Otherwise (or if Hard Mode is enabled), it provides only 10 oil.

If the FullGameSave instance var is not enabled, OilBarrels can be used again when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| FillSound || File (.snt) || || Sound played when lantern is filled. Incorrectly defined as a string in EntityTypes.cfg.
|-
| EmptySound || File (.snt) || || Sound played when barrel is empty. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

== EmotionStone ==

The memory capsule entities found in the game. Interacting with an EmotionStone causes an emotion flash effect to display, fading the screen to white and displaying a message.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DescCat || String || || Category of text shown when in focus.
|-
| DescEntry || String || || Entry of text shown when in focus.
|-
| TextCat || String || || Category of text shown when interacted with. Typically "EmotionStone".
|-
| TextEntry || String || || Entry of text shown when interacted with.
|-
| Sound || File (.snt) || || Sound played when interacted with.
|-
|}

== NPC ==

Non-Player Characters are non-enemy characters. Agrippa and Alexander as they appear in-game are NPCs. Their only purpose is to stand in place and look at the player (if you enable the option).

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveHeadBones || String || || List of bones that is rotated when the NPC rotates its head.
|-
| MoveHeadBoneMuls || String || || List of floats specifying how much each bone shall be rotated (-1 to 1).
|-
| HeadMoveSpeedMul || Float || 1 || Speed multiplier that that determines move speed based on distance to wanted angle.
|-
| HeadMoveMaxSpeed || Float || 1 || The max speed that the head moves in.
|-
| MaxHeadAngle || Float || 30 || The max angle that the head can turn when looking at the player.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| FollowPlayerArea || String || || When player is in this area, the NPC will look at him.
|-
| Awake || Bool || true || If the NPC is awake and looks at the player when in area.
|-
|}

== LevelDoor ==

A LevelDoor transports the player to the specified level when interacted with. The locked sounds, text, and destination can be entered in the Level Editor itself.

LevelDoors can also teleport the player (without a loading screen) if the same map is picked.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| EnterSound || File (.snt) || || Sound played when entering door. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ExitSound || File (.snt) || || Sound played when entering new map after having interacted with door. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| TextEntry || String || || The text shown when door is in focus. Category is always Levels
|-
| StartPos || String || || The start position of the next map that the player is transported to.
|-
| MapFile || File (.map) || || The file of the next map.
|-
| Locked || Bool || false || If the door is locked.
|-
| LockedSound || File (.snt) || || Sound heard if locked and interacted with.
|-
| LockedTextCat || String || || Category of message shown if locked and interacted with.
|-
| LockedTextEntry || String || || Entry of message shown if locked and interacted with.
|-
| ShowStats || Bool || true || If stats of map it leads to should be shown (NOT IN USE) Non-functional. Formerly used to display a completion percentage.
|-
|}

== CritterBug ==

Critters like rats, roaches, or fish on the ground (or in the case of fish, water). They move around the room they are placed in and run away from the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MeshOffsetRot || Vector3 || 0 0 0 || The mesh offset rotation.
|-
| MeshOffsetPos || Vector3 || 0 0 0 || The mesh offset position.
|-
| MaxSpeedNormal || Float || 0.5 || Max speed when in normal state
|-
| MaxSpeedAfraid || Float || 1.3 || Max speed when in the scared state
|-
| Gravity || Float || 9.8 || Amount of gravity applied.
|-
| HasRandomPauses || Bool || false || If the critter shall have random pauses
|-
| RandomPauseTimeMinMax || Vector2 || 1 3 || Random time length of pause
|-
| RandomMoveTimeMinMax || Vector2 || 2 6 || Random time length of movement (between pauses)
|-
| PlayerFleeDistance || Float || 3 || The distance from player which it begins to flee
|-
| FleeMul || Float || 2.1 || Factor for moving away from player (if fleeing)
|-
| BackToSpawnPointMul || Float || 0.1 || Factor for moving back to spawn point
|-
| WanderCircleRadius || Float || 4 || Picture a circle in front critter at a certain distance. A point inside the circle is randomly selected and then the vector from the critter to this point is the speed added. The larger the circle, the more random the walk.
|-
| WanderCircleDist || Float || 2 || The distance at which the wander circle is placed. The higher the distance, the more likely the critter is to move forward.
|-
| NormalSound || File (.snt) || || Sound made when in normal state
|-
| NormalSoundRandMinMax || Vector2 || 1 3 || Random time length between normal sounds. x=min, y=max
|-
| ScaredSound || File (.snt) || || Sound made when in afraid state
|-
| ScaredSoundRandMinMax || Vector2 || 1 3 || Random time length between afraid sounds. x=min, y=max
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
|}

{{HPL2 InstanceVars Prop}}

== CritterSpider ==

A unused critter similar to the spider enemies from [[wikipedia:Penumbra: Overture|Penumbra: Overture]]. Capable of climbing walls and ceilings, as well as attacking the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MaxIdleSpeed || Float || 0.5 ||
|-
| MaxHuntSpeed || Float || 0.75 ||
|-
| HitSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSoundRandMinMax || Vector2 || 1 3 ||
|-
| AttackSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| AttackPlayerDistMinMax || Vector2 || 1 3 ||
|-
| HuntPlayerDist || Float || 8 ||
|-
| HuntTimeMinMax || Vector2 || 10 30 ||
|-
| MoveTimeMinMax || Vector2 || 4 8 ||
|-
| IdleTimeMinMax || Vector2 || 0.4 2 ||
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
| AttackSizeRadius || Float || 0.3 ||
|-
| AttackOffset || Vector3 || 0 0 1 ||
|-
| AttackDamageMinMax || Vector2 || 5 15 ||
|-
| AttackForce || Vector2 || 5 1 ||
|-
| AttackStrength || Int || 1 ||
|-
| AttackHitSound || File (.snt) || ||
|-
|}

{{HPL2 InstanceVars Prop}}

== Enemy_Grunt ==

An Enemy_Grunt entity is a standard enemy entity, used for the Grunt, Brute, and Suitor. Enemy entities require advanced setup, and should include animations added through Settings > Animations. Enemy properties can be modified in the entity type window, like certain sounds and music tracks playing, the enemy's awareness levels and damage, speed and other similar settings. An enemy does not use a collision box, but instead a skeleton and the aforementioned properties to determine how to collide/hit something.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 15 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 10 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 3.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 2.0 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 4.5 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.5 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 5 || The distance where the move toward enemy check starts
|-
| IdleExtraTimeMin || Float || 2 || Min time between extra idle animations
|-
| IdleExtraTimeMax || Float || 6 || Max time between extra idle animations
|-
| IdleExtraNum || Int || 3 || Number of extra idle animations
|-
|}

{{HPL2 InstanceVars Enemy}}

== Enemy_ManPig ==
{{clr}}
{{ReqVer|1.3}}

An enemy type ported from A Machine For Pigs. Compare to the [[HPL2/AMFP/NewEntities#Enemy_ManPig|AMFP version]] of the enemy.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| Quadruped_Walk_ForwardSpeed || Float || 1.0 || Forward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_BackwardSpeed || Float || 1.0 || Backward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_ForwardAcc || Float || 2.0 ||
|-
| Quadruped_Walk_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_Run_ForwardSpeed || Float || 3.0 || Forward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_BackwardSpeed || Float || 2.0 || Backward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_ForwardAcc || Float || 4.0 ||
|-
| Quadruped_Run_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_StoppedToWalkSpeed || Float || 0.05 || Speed at which the walk animation is played when on all fours
|-
| Quadruped_WalkToStoppedSpeed || Float || 0.02 || Speed at which walk goes to stopped when on all fours
|-
| Quadruped_WalkToRunSpeed || Float || 2.0 || Speed at which walk turns to run animation when on all fours
|-
| Quadruped_RunToWalkSpeed || Float || 0.9 || Speed at which run turns to walk when on all fours
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 1 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 6 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 2.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 0.5 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 1.0 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.25 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 6 || The distance where the move toward enemy check starts
|-
| IsTelsa || Bool || false || If this is the tesla pig
|-
| TeslaSoundLoop || File (.snt) || || Sound file played when the tesla's proximity effects are active. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ChaseSound || File (.snt) || || Played when the pig is chasing. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Instance Vars
! Name !! Type !! Default !! Description
|-
| Pose || String || Biped || The pose of the enemy to start with Can be "Biped" or "Quadruped".
|-
| ThreatenOnAlert || Bool || false || If the pig should stand still and threaten instead of walking towards player when in alert mode.
|-
| FleeFromPlayer || Bool || false || The pig will flee instead of hunting (threaten if ThreatenOnAlert). Disabled if far enough away. Will attack if cornered.
|-
| AutoDisableAfterFlee || Bool || false || If pig should be disabled after having fled (if possible)
|-
| LanternSensitivity || Float || 1 || A modifier for how quickly the pig reacts to being shined on by the lantern. Not defined in EntityTypes.cfg.
|-
| IdleBehavior || String || None || The behavior used when there are no patrol nodes left to walk. Can be "None", "Stalk", or "Track".
|-
| PlayActivateSound || Bool || true || If the enemy can play its EnabledSound.
|-
| AllowZeroNodeWaitTimes || Bool || false || If set to true, path node wait times with value 0 actually mean no waiting Normally, specifying a wait time of 0 in <code>AddEnemyPatrolNode</code> results in a wait time of 1-3 seconds.
|-
| PatrolMoveSpeed || String || Walk || Whether this pig walks or runs along its patrol Can be "Walk" or "Run".
|-
| DamageMul || Float || 1 || Multiplier for the enemy's attack damage. Not defined in EntityTypes.cfg.
|-
| RunSpeedMul || Float || 1 || Multiplier for the enemy's run speed. Not defined in EntityTypes.cfg.
|-
| HuntPauseTimeMul || Float || 1 || Multiplier for wait time between attacks.
|-
|}

== Enemy_Waterlurker ==

Enemy type of the "water monster". Since you can't assign animations to it, you might as well just use the normal waterlurker of the base game unless you want to change its properties (such as damage, movement speed, or music played).

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0.6 || The y-distance from the enemy that the player is detected.
|-
| EatDamage || Float || 20 || The damage dealt to food being eaten
|-
| AfterAttackPauseTime || Float || 0 || The amount of timer lurker waits after an attack
|-
| SplashPS_Walk || File (.ps) || || Particle system created at surface when walking.
|-
| SplashPS_Run || File (.ps) || || Particle system created at surface when running.
|-
| SplashPS_Eat || File (.ps) || || Particle system created at surface when eating.
|-
| SplashPS_Attack || File (.ps) || || Particle system created at surface when attacking.
|-
| SplashSound_Walk || File (.snt) || || Sound played when walking.
|-
| SplashSound_Run || File (.snt) || || Sound played when running.
|-
| SplashSound_Eat || File (.snt) || || Sound played when eating.
|-
| SplashSound_Attack || File (.snt) || || Sound played when attacking.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0 || If equal or below 0 the default in data file is used! The y-distance from the enemy that the player is detected.
|-
|}

== PlayerHands ==

Player's hands. Unless you want to make a different looking hand for a full conversion mod, you don't have to worry about this.

== HandObject ==

The only available HandObject is the lantern. It is used in conjunction with a <code>.ho</code> config file to place it properly in PlayerHands.

Mostly a remnant of cut items that functioned as weapons, like in [[wikipedia:Penumbra: Overture|Penumbra: Overture]], including the pickaxe from that game.

HPL2/AMFP/Infection

2026-02-07T20:14:59Z

BoxFigs: /* Missing parts */

= Infection =

Infection is a mechanic which was cut from the final game, but it wasn't fully removed from it.

== Overview ==

The mechanic is quite similar to sanity from TDD. It is a meter which fills up in certain circumstances and plays visual and sound effects, which depend on the meter's value.

The infection meter is primarily changed by Infection areas. There are multiple of them placed in the game, but they all have been deactivated (which means that they can be restored). Infection areas can either increase or decrease infection. The only other functional method of changing infection (outside of scripting) is by standing in a Liquid area with the InfectionLevel variable set.

There are 4 levels of infection, all of which play increasingly noticeable screen effects (sepia, image trails, and radial blur).
{|class=wikitable
! Level !! Value Range (Check) !! Value (Set) !! Effects
|-
| 0 || 0 || 0 ||
|-
| 1 || 1-25 || 30 ||
|-
| 2 || 26-50 || 50 ||
|-
| 3 || 51-75 || 70 || Running disabled
|-
| 4 || 76-100 || 90 || Running disabled, -50% speed
|-
|}

Infection levels are calculated differently when going from level to value when checking infection level compared to setting infection level. Because of this quirk, setting infection to level 1 actually puts it in the level 2 range.

The meter goes down automatically after the player leaves the infected area. It will gradually fall to zero, unless the player has gathered above 80 infection; in that case, they will die after 2 seconds (unless "faux mode" is enabled). Interestingly, infection no longer decreases over time above 75, which leaves a tight margin of 5 infection points which won't kill the player but will not decrease.

Currently the only way to view the meter (aside from the audiovisual effects) is to press F1 in debug mode and turn on player info.

== Other evidence ==

According to these sections of '''game.cfg''', the infection system was a slightly modified version of the sanity mechanic.

<syntaxhighlight lang="xml">
<Infection
EventsFile = "misc/main_sanity_events.cfg"

MinTimeBetweenEvents = "300"
MaxEventSanity = "65"

MaxSanity_LongWait = "65"
MaxSanity_MedWait = "45"
MaxSanity_ShortWait = "25"

TimeBetween_LongWait = "270"
TimeBetween_MedWait = "180"
TimeBetween_ShortWait = "80"

MinExamineInfection = "50"

InfectionArea_CheckTimeMin = "1"
InfectionArea_CheckTimeMax = "2"
/>

<Player_Infection

HitZoomInSpeed = "3.5"
HitZoomOutSpeed = "0.6"
HitZoomInFOVMul = "0.06"
HitZoomInAspectMul = "0.15"

InfectionDecreaseSpeed = "0.75"
InfectionDecreaseLimitLevel = "3"

InfectionVeryHighLimit = "80"
InfectionEffectsStart = "35"

InfectionWaveAlphaMul = "1"
InfectionWaveSpeedMul = "1"

CheckEnemyNearOrSeenInterval = "0.3"

NearEnemyDecrease = "0.3"
NearCritterDecrease = "0.1"

StartSwayMinInfection = "15"
SwayMaxSavedPositions = "30"

HighInfectionLimitForDeathTimer = "80"
TimeUntilDeathAtHighInfection = "2"

LightLampMinInfectionIncrease = "0.1"
LightLampMaxInfectionIncrease = "5"

NumberOfInfectionLevels = "4"

InfectionLevelOneSpeedMultiplier = "1.0"
InfectionLevelTwoSpeedMultiplier = "1.0"
InfectionLevelThreeSpeedMultiplier = "1.0"
InfectionLevelFourSpeedMultiplier = "0.5"

MaxInfectionLevelAtWhichPlayerCanRun = "2"

GradientThresholdOffset = "1.1"
GradientFallofExponent = "8.0"
InfectionMapZoom = "0.95"

VomitEffectDuration ="3.0"

InfectionEffectGrowSpeed = "1"
/>
</syntaxhighlight>

However, in the game it uses a separate meter (which is visible via the aforementioned debug menu method).

The mentioned sanity events config file contains exactly the same data as TDD, which means that it wasn't used in the end.

Infection was supposed to increase near creatures, yet the config still has the old sanity property names:

<syntaxhighlight lang="xml">
NearEnemyDecrease = "0.3"
NearCritterDecrease = "0.1"
</syntaxhighlight>

The proper names for these are <code>NearEnemyIncrease</code> and <code>NearCritterIncrease</code>, although only CritterSpider increases infection, as a result of repurposed TDD code.

These property names were changed to replace "Sanity" with "Infection", but are entirely unused:

<syntaxhighlight lang="xml">
LightLampMinInfectionIncrease = "0.1"
LightLampMaxInfectionIncrease = "5"
</syntaxhighlight>

ManPig enemies have unused vomit animations and unused entity parameters, such as:

* DistanceAtWhichFleeingPigVomitAttacks
* MinimumTimeBetweenVomitAttacks
* MinTimeBeforeIgnoringPlayerAfterVomit

These seem to indicate that ManPigs would have attacked the player by vomiting, increasing the infection meter. The C++ source code shows that being vomited on would instantly set infection to the maximum level:

<syntaxhighlight lang="c++">
void cLuxPlayer::VomitDamage()
{
mfTimeSinceLastVomit = 0.0f;

/*if ( GetInfectionLevel() < 3 )
{
SetInfectionLevel( 3 );
}
else*/ if ( GetInfectionLevel() < 4 )
{
SetInfectionLevel( 4 );
}
}
</syntaxhighlight>

A particle effect called "''ps_pig_attack_vomit''" was also left in the game.

== Missing parts ==

When the infection is used in-game by enabling the infection areas, some errors get printed to the log:

<pre>
ERROR: Could not load sound 'infection_loop_1'
ERROR: Can't find sound 'infection_loop_1'!
ERROR: Couldn't create SoundEntity 'infection_drain_high.snt'
ERROR: Couldn't create SoundEntity 'infection_heartbeat.snt'
WARNING: Could not find language file entry 'InfectionHigh'
ERROR: Couldn't create SoundEntity 'infection_pant.snt'
</pre>

This indicates that some of the sound entity (.snt) files are missing. They don't have the raw sound files (.ogg) either. However, they use the same naming scheme as TDD's sanity sounds, so it's likely that the TDD sounds were simply renamed.

Furthermore, the game displays an empty hint when player reaches level 4 of infection. Its lang file name is "InfectionHigh", which means that it can be remade and will display automatically. It is unknown if hints for other infection levels exist.

HPL2/Engine Scripts

2025-10-17T01:54:56Z

BoxFigs: /* Sounds & Music */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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

{{bug|When loading a map from the debug menu, music from the previously loaded map cannot be stopped! It can only be overridden by playing another instance of music at the same priority level. To work around this, call <code>PlayMusic</code> first, where the volume is greater than 0 and the priority matches the previous map's music, then call <code>StopMusic</code> immediately afterward.}}

<syntaxhighlight lang="c++">
void AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function when it stops. Callback syntax: <code>void MyFunc(string &in asProp)</code>

#''asProp ''- internal name of the prop
#''asAnimation ''- animation to play
#''afFadeTime ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call when the animation ends

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

#''asName'' - internal name
#''afAngle'' - angle
#''abAutoMove'' - true = wheel physically moves to the new angle; false = angle is changed without moving the wheel

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:47:30Z

BoxFigs: /* Levers, wheels and buttons */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function when it stops. Callback syntax: <code>void MyFunc(string &in asProp)</code>

#''asProp ''- internal name of the prop
#''asAnimation ''- animation to play
#''afFadeTime ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call when the animation ends

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

#''asName'' - internal name
#''afAngle'' - angle
#''abAutoMove'' - true = wheel physically moves to the new angle; false = angle is changed without moving the wheel

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:46:44Z

BoxFigs: /* Levers, wheels and buttons */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function when it stops. Callback syntax: <code>void MyFunc(string &in asProp)</code>

#''asProp ''- internal name of the prop
#''asAnimation ''- animation to play
#''afFadeTime ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call when the animation ends

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in asName, float afAngle, bool abAutoMove);
</syntaxhighlight>

Moves a wheel to a certain angle.

#''asName'' - internal name
#''afAngle'' - angle
#''abAutoMove'' - true: wheel physically moves to the new angle; false: angle is changed without moving the wheel

<syntaxhighlight lang="cpp">
void SetWheelInteractionDisablesStuck(string &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:41:48Z

BoxFigs: /* Props */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in asCallback);
</syntaxhighlight>

Makes the prop play an animation and calls a function when it stops. Callback syntax: <code>void MyFunc(string &in asProp)</code>

#''asProp ''- internal name of the prop
#''asAnimation ''- animation to play
#''afFadeTime ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call when the animation ends

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:39:21Z

BoxFigs: /* Props */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:38:44Z

BoxFigs: /* Props */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:32:16Z

BoxFigs: /* Player */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-10-16T18:31:26Z

BoxFigs: /* Player */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in asTextEntry);
</syntaxhighlight>

Sets the message that appears when the player dies.

#''asTextCategory'' - the category in the .lang file, usually "Hints"
#''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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-09-25T02:35:09Z

BoxFigs: /* Props */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''abFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-09-25T02:34:45Z

BoxFigs: /* Props */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in asName, bool abActive, bool abFadeAndPlaySounds);
</syntaxhighlight>

Turns the texture illumination, billboards, particles, light flicker, and sounds of a prop on or off.

Can be used on coal to give it the black color it should have.

#''asName'' - internal name
#''abActive'' - active state
#''afFadeAndPlaySounds'' - if all effects should fade in/out or not

<syntaxhighlight lang="c">
void SetPropActiveAndFade(string &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-09-05T06:25:27Z

BoxFigs: /* General */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 ''- starting character of the string, with 0 being the first character
#''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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

Audacity

2025-09-05T04:05:41Z

BoxFigs: /* Reverb settings */

= Audacity =

[https://www.audacityteam.org/ Audacity] is a free and open-source audio editor. It is great for simple audio edits and applying effects.

== Flashback Voice Effect ==

Audacity can be used to create the flashback voice effect from the original Amnesia game. This effect can be achieved with the following steps:

# Effect > Reverse (This reverses the audio back in time).
# Use a reverb effect of your choice. Make sure to not make it too strong, as it might overwhelm the actual speech.
# Effect > Reverse.

===Reverb settings===
* Effect > Reverb:
**Room Size: 10
**Pre-delay: 10
**Reverberance: 40
**Damping: 0
**Tone Low: 100
**Tone High: 100
**Wet Gain: -1
**Dry Gain: 0
**Stereo Width: 100
 
{{warning|GVerb is only available in older versions of Audacity. It was able to be readded for a time with a plugin, though it appears it's no longer compatible with more recent versions.}}
* Effect > GVerb:
**Roomsize: 10
**Reverb time: 0.75
**Damping: 0
**Input bandwidth: 1
**Dry signal level: 0
**Early reflection level: -15
**Tail level: -17.5

== Convert to OGG format ==
OGG format is the recommended format for audio files for HPL, and Audacity comes with support for exporting in OGG.

If you need to convert an MP3 (or any other audio), simply import (or open) an audio file into Audacity, then click on ''File > Export'' and choose OGG Vorbis for the file type.

HPL2/Engine Scripts

2025-08-29T06:32:58Z

BoxFigs: /* Player */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Reduces the sanity of the player.

#''afAmount'' - amount of sanity damage done
#''abUseEffect'' - if a sound is played and screen effects are shown when the sanity damage is dealt

<syntaxhighlight lang="c++">
void GivePlayerDamage(float afAmount, string &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<syntaxhighlight lang="c++">
bool GetLanternActive();
</syntaxhighlight>

Checks whether the player is currently using the lantern.

<syntaxhighlight lang="c++">
void SetLanternDisabled(bool abX);
</syntaxhighlight>

Enables/Disables the player's ability to use the lantern.

<syntaxhighlight lang="c++">
void SetLanternLitCallback(string &in asCallback);
</syntaxhighlight>

Sets the function to call when the player uses the lantern. Callback syntax: <code>MyFunc(bool abLit)</code>

<syntaxhighlight lang="c++">
void SetMessage(string &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/TDD/Entity Types

2025-08-28T20:32:34Z

BoxFigs: /* Item */

{{TocRight}}

This page lists the different types of entities found within the HPL2 engine. The type determines how the entity will be set up, what kind it is, what it does under different circumstances etc. Using the Model Editor you can identify and specify which type an entity has and its type vars, in Settings > User defined variables. In the Level Editor, the different types have different settings applicable for them, known as instance vars. For example, a MoveObject type will have the OffsetArea box available in the Level Editor, and an Item (Note) type will have a NoteText box available.

A list of all the types and subtypes can be found in the table of contents to the right.

== StaticProp ==

A StaticProp entity resembles a static object. They have no available type properties, but they can still use physics bodies (collision boxes) and have mass/gravity. Note that they cannot be interacted with in the game, and cannot be disabled. If you need this feature, use Object (Static) instead.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CastShadows || Bool || true || If entity casts shadows.
|-
| IsAffectedByDecal || Bool || true || If decals can be created on entity.
|-
|}

== CommentaryIcon ==

A CommentaryIcon entity is simply an object that can execute commentary sound files, as it was done in the main game. These only appear if the player has "Commentary" enabled in their settings.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| RotateSubMesh || String || || The name of the submesh that is to be rotated
|-
|}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| File || File (.comment) || || The .comment file for the commentary.
|-
|}

== Object ==

Objects are entities that can be activated/deactivated, broken, and interact with physics.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| BreakActive || Bool || false || If entity is broken when hit hard enough or health is 0.
|-
| BreakDestroyJoints || Bool || false || If all physics joints should be destroyed when broken.
|-
| BreakMinEnergy || Float || 100 || The minimum energy needed for breakage. Energy = Object1Speed * Object1Mass + Object2Speed * Object2Mass. Speed = m/s. If Object 2 is floor or something static, its speed is always 0 and does not contribute to total energy!
|-
| BreakEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| BreakEntityAlignBody || String || || The body BreakEntity uses to align itself when created. No entity is created if left empty.
|-
| BreakSound || File (.snt) || || The sound made when broken.
|-
| BreakParticleSystem || File (.ps) || || Particle system shown when broken.
|-
| BreakImpulse || Float || 4 || Impulse (speed in m/s really) added to all bodies in BreakEntity when created. The direction of impulse is outwards from center of entity.
|-
| HitDamageAmount || Float || 5 || The amount of damage made when hitting an enemy or player.
|-
| HitDamageStrength || Int || 1 || The strength of the damage.
|-
| MinHitDamageSpeed || Float || 3 || The minimum speed (m/s) needed for damage to be made.
|-
| LifeLength || Float || 0 || A time after which the entity automatically breaks. 0=lasts forever.
|-
| IsFood || Bool || false || If this is food for some enemies and can be used to lure them. Needs to have break active and health determines how long the food lasts. Waterlurkers are the only enemy type that is lured by and eats food objects.
|-
| ShowHints || Bool || true || If a hint can be triggered by interacting with the prop.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| ContainedItem || String || None || An item that is created when entity breaks. Must match an entity file name (extension .ent optional) in the "items" folder.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
| IsInsanityVision || Bool || false || If the prop is only shown when insanity is low enough.
|-
| VisionMaxSanity || Float || 30 || The max sanity the player can have for prop to show if it is an insanity vision. The object will only be visible if the player's sanity is less than this value.
|-
|}

=== Static ===

Not to be confused with an actual static object. This Object subtype is a generic object with common properties. The static subtype simply disables any additional properties from the other subtypes. An Object (Static) is similar in concept to a StaticProp type entity, however the Object (Static) can be deactivated, can break, has physics, and can have an interact callback set.

=== Grab ===

A Grab subtype is a normal Object entity with the ability to be grabbed by the player in the game. In order for this to work, the object must have a mass above 0.

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| GrabUseDepth || Bool || false || If GrabDepth is used. If not the interaction distance is used.
|-
| GrabDepth || Float || 1.5 || The distance which a grabbed object is automatically placed at.
|-
| GrabDepthInc || Float || 0.15 || Steps that the entity will move in when moving the mouse scroll.
|-
| GrabMinDepth || Float || 1.0 || Minimum distance the entity can be from player when grabbed.
|-
| GrabMaxDepth || Float || 2.2 || Maximum distance the entity can be from player when grabbed.
|-
| GrabUseOffset || Bool || false || If rotation and position offset is used. If not offset will be relative to the interact position.
|-
| GrabPositionOffset || Vector3f || 0 || Positional offset of entity.
|-
| GrabRotationOffset || Vector3f || 0 || Rotational offset of entity. It will automatically rotate to this when grabbed.
|-
| GrabThrowImpulse || Float || 10 || The speed (m/s) at which the entity is thrown.
|-
| GrabMassMul || Float || 0.1 || How much the object will weight when grabbed. Useful for heavier objects since they can wreck mayhem otherwise. 0.5% means half (50%) of the original weight.
|-
| GrabForceMul || Float || 1 || Change how much force is added to grabbed object.
|-
| GrabTorqueMul || Float || 1 || Change how much torque is added to grabbed object.
|-
| GrabUseRotation || Bool || true || If rotation should be used on grabbed object
|-
| GrabSkipNonOuterBodies || Bool || false || If true, then bodies that are inside a chain (has two or more joints attached to it) will not be grabbed.
|-
|}

=== Push ===

Similar to the Grab subtype, the Push subtype allows the player to push the object by taking hold of it and walking or right clicking. Examples include large rocks and the bed covering the hole in the floor in the Prison - Southern Block.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| PushAtPoint || Bool || false || If the push force should be applied to the point at the object where interaction took place.
|-
| PushForceMul || Float || 1 || Multiplier for force applied. Used to fine tune interaction.
|-
| PushImpulse || Float || 2 || Impulse added when thrown.
|-
|}

=== Slide ===

A Slide Object is similar to the Grab subtype, except it can only be slid in a single direction for a certain amount. An existing (but unused) entity that uses this is the secret floor carpet you can slide to the side.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
|}

== SwingDoor ==

A SwingDoor entity is standard hinged door. Any door you can grab and swing open is considered a SwingDoor. To use a SwingDoor, you need to attach joints to where you want the door to swing around. These are usually placed by the hinges of the door. On the joint you can set the min and max values to limit how much the door can be opened. These are usually approximately 90 degrees apart in either positive or negative directions.

If the FullGameSave instance var is not enabled, SwingDoors will reset to their initial open amount when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the door is interacted with. Meaning that interacting with any part of the entity will work.
|-
| CloseOnSound || File (.snt) || || Sound played when the door is closed.
|-
| CloseOffSound || File (.snt) || || Sound played when the door is opened.
|-
| LockOnSound || File (.snt) || || Sound played when the door is locked.
|-
| LockOffSound || File (.snt) || || Sound played when the door is unlocked.
|-
| InteractLockedSound || File (.snt) || || Sound made when player interacts with a locked door.
|-
| Breakable || Bool || false || Can the door be broken.
|-
| DamageMesh1 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage1
|-
| DamageMesh2 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage2
|-
| BrokenEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| DamageSound || File (.snt) || || Sound made when a new damage mesh is used.
|-
| DamagePS || File (.ps) || || Particles created when a new damage mesh is used.
|-
| BreakSound || File (.snt) || || Sound made when broken.
|-
| BreakPS || File (.ps) || || Particles created when broken.
|-
| BreakImpulse || Float || 3 || Impulse set to objects in broken mesh. Incorrectly defined as a sound file in EntityTypes.cfg.
|-
| HealthDamage1 || Float || 66 || Health when damage mesh 1 is used.
|-
| HealthDamage2 || Float || 33 || Health when damage mesh 2 is used.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Locked || Bool || false || If the door is locked
|-
| OpenAmount || Float || 0 || The amount the door is open. 0 - 1.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
|}

== Lever ==

A Lever entity is an entity that can be swung between states to trigger callbacks. A lever requires a joint to swing around.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitSound || File (.snt) || || Sound played when at min limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MaxLimitSound || File (.snt) || || Sound played when at max limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MinLimitStuck || Bool || false || If the lever becomes stuck when reaching min. Missing from EntityTypes.cfg.
|-
| MaxLimitStuck || Bool || false || If the lever becomes stuck when reaching max. Missing from EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the position.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The initial stuck state for the lever. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

== Wheel ==

A Wheel entity is a wheel that can be turned. They use states similar to the levers. Some wheels can be turned indefinitely and some (mostly valves) can be turned for a fixed amount in order to trigger an event. Wheels require a joint.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the wheel is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
| MinLimitSound || File (.snt) || || Sound played at min limit
|-
| MaxLimitSound || File (.snt) || || Sound played at max limit
|-
| StuckSound || File (.snt) || || Sound played when stuck.
|-
| SlowDownRotation || Bool || true || If rotation should be slowed to 0 when not interacting.
|-
| SkipMiddleState || Bool || true || If the middle state (when not in max or min) should be skipped by script and connections.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
|}

== MultiSlider ==

A sliding-type lever that can be set to multiple states. Used for the gear levers in the Sewer.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
| NumOfStates || Int || 3 || The number of states used.
|-
| StickToStateMaxDist || Float || 0.1 || The distance from a state that the slider sticks.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| AutoMoveToCurrentState || Bool || true || If body should automove to current state when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the postion.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| ChangeStateSound || File (.snt) || || Sound played when state is changed Incorrectly defined as a string in EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| ChangeStateCallback || String || || Called when state changes Syntax: <code>void MyFunc(string &in asEntity, int alState)</code> Used instead of ConnectionStateChangeCallback, as this entity type can have more than two possible states.
|-
|}

== Lamp ==

A Lamp entity is a light source. If they are unlit, they can be lit by the player, consuming a tinderbox. Examples are torches and candles.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CanBeLitByPlayer || Bool || true || If the player can use a tinderbox on it to light it.
|-
| CanBeGrabbed || Bool || false || If it can be grabbed by the player. No effect. Presumably intended to make the entity behave like a Grab Object, yet this is unimplemented.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Lit || Bool || true || If the lamp is lit or not.
|-
| ConnectedLight || String || || Name of a light (that is not in an entity!) that will be connected to the this light and will increase/decrease in color as the lamp is turned on/off.
|-
| ConnectionLightAmount || Float || 1 || The amount to multiply the lamp's color by before adding it to the connected light's color.
|-
| ConnectionLightUseOnColor || Bool || true || If the on color should always be used. If false the light color (which might be flickering) is used.
|-
| ConnectionLightUseSpec || Bool || false || If the specular of the lamp color should be used.
|-
|}

== Button ==

A Button entity acts like a Lever, except it does not use a joint. It simply changes its connection state and toggles effects when interacted with.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| SwitchedOn || Bool || false || If the button starts as on or off
|-
| CanBeSwitchedOn || Bool || true || If player can switch it on.
|-
| CanBeSwitchedOff || Bool || false || If player can switch it off.
|-
|}

== Photocell ==

A prop that changes its texture illumination and connection state based on the light level around it. Presumably a leftover from Lux Tenebris, which featured light-based puzzles.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| LightLevelOnLimit || Float || 0.9 || Light level above this value turns the photocell on.
|-
| LightLevelOffLimit || Float || 0.1 || Light level below this value turns the photocell off.
|-
|}

== MoveObject ==

A MoveObject entity is an entity that can be specifically moved on a single axis through the use of scripting. It can be set to either Angular or Linear. Angular rotates the object around its own center point, unless otherwise specified by the use of an OffsetArea. Linear moves the object in a direction for a specified amount. Note that a linear move object can only move on one axis. You can pick X, Y, or Z in the entity and this cannot be changed mid-game. If you want the same object to move on more than 1 axis (for example left then forward) you can switch out the entity with an identical one that uses another axis. The script to move a MoveObject is <code>SetMoveObjectState</code> and <code>SetMoveObjectStateExt</code> (see [[HPL2/Engine Scripts|Engine Scripts]]).

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveObjectType || String || Linear || The way the object moves. Linear means position changes and Angular means rotation changes. Can be "Linear" or "Angular".
|-
| OpenAmount || Float || 1.0 || Linear: How much of the MoveAxis size that will mean that it is open. Angular: 1=90 degrees. 0.5=45deg and 2=180deg (any numbers inbetween are okay of course)
|-
| MoveAxis || String || X || he axis that the movement is about. For angular it is rotation axis and for linear it is the position axis that is changed. Can be "X", "Y", or "Z".
|-
| OpenAcc || Float || 5.0 || The acceleration for reaching OpenSpeed
|-
| OpenSpeed || Float || 1.0 || The goal speed when opening.
|-
| CloseAcc || Float || 5.0 || The acceleration for reaching CloseSpeed
|-
| CloseSpeed || Float || 1.0 || The goal speed when closing.
|-
| AutoMove || Bool || false || If the door should move towards some goal automatically.
|-
| AutoMoveStateGoal || Float || 0.0 || The amount (relative to the what is considered open) that it shall move towards.
|-
| AutoMoveAcc || Float || 9.0 || The acceleration when automoving
|-
| AutoMoveSpeed || Float || 5.0 || The goal speed when automoving
|-
| AutoMoveSlowdownDist || Float || 0.1 || The distance from state goal where it begins to slow down (in meters for linear and degrees for angular).
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| AngularOffsetArea || String || || When mode is angular, this the point it rotates around. If empty, it rotates around its center.
|-
|}

== Item ==

Item entities become inventory items when interacted with. They glow when in pickup range.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SubItemTypeName || String || || Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
| ImageFile || File (.tga/.dds/.jpg/.jpeg/.png) || || The icon shown in the inventory when picked up.
|-
| PickSound || String || Generic || The sound played when picked up. Must match a sound file name in the "ui" folder, starting with "pick_".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CustomSubItemTypeName || String || || If not emtpy it overrides SubItemTypeName in entity file. Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
|}

=== Puzzle ===

A Puzzle subtype item is a general item with no extra properties. Use this if you only need an inventory item to be used to trigger a scripted action. Other subtypes have special properties, but Puzzle only has the ability to be collected and used from the inventory. When used, it's loaded onto the crosshair so the player can use it on objects.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| TempVar || Float || 0 || User specfic usage.
|-
|}

=== Coins ===

Unused item type for the cut Thaler items. Thalers were once used to unlock Chests and use OilBarrels, with only the former functionality remaining.

{{warning|You can create custom coin items, but there is a single language entry which is hardcoded into the engine and can't be changed. This means that even if all the others are changed, looking at Chests will always say "Locked. Costs X Thalers to open."}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CoinAmount || Int || 10 || The amount of coins it contains.
|-
|}

=== Note ===

A Note item is an item that adds text to the player's journal. It displays itself when picked up. The note can be narrated, in which case it will automatically close once it's finished. If it isn't voiced, the player must close it. Use this if you want to make a Note item using a custom model or custom properties that differ from the main notes.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| NoteText || String || || The text and name of entry for note. Entry names for these are calculated: 'Note_'+NoteText+'_Name' and 'Note_'+NoteText+'_Text'
|-
| OpenNoteInJournal || Bool || true || If the journal should be opened when the note is picked up.
|-
| UseNarration || Bool || false || If the note has narration.
|-
|}

=== Diary ===

A Diary item is nearly identical to the Note item. Instead, it adds itself to the Diary section of the player's journal, whereas the Note adds itself to the Notes section. Additionally, diary entries are grouped together, so that when one is split into multiple parts, the player will always read them in order, regardless of the specific Diary items that were picked up.

Diaries are also always voice enabled, while Notes have the option for it. As such, a Diary without any voice files defined in its text will instantly close the journal on pickup.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DiaryText || String || || The text and name of entry for diary. Entry name for these calculated: 'Diary_'+DiaryText+'_Name'+Idx and 'Diary_'+DiaryText+'_Text'+Idx. Idx starts at 1.
|-
| DiaryCallback || String || || A special callback for diary pickup. Syntax: <code>void Func(string &in asItem, int lDiaryIdx)</code>. Call <code>ReturnOpenJournal(false)</code> to not open diary in journal after callback.
|-
|}

=== Lantern ===

A Lantern item can be picked up like a normal item, but is added as a lantern to the inventory. While having this item, the player can press F to toggle it, or click it in the inventory. Note: This is NOT the lantern model in the player's hands, only the item that gives it to the player. If you want a custom lantern model, you can follow [https://www.frictionalgames.com/forum/thread-12391.html this guide].

=== Health ===

A Health item acts like a health potion (Laudanum). When used, it increases the player's health by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much health is regained when used.
|-
|}

=== Sanity ===

A Sanity item acts like a sanity potion. When used, it increases the player's sanity by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much sanity is regained when used.
|-
|}

=== LampOil ===

A LampOil item acts like an oil potion. When used, it increases the player's lantern oil by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| OilAmount || Float || 25 || How much oil is regained when used.
|-
|}

=== Tinderbox ===

A Tinderbox item adds itself to the player's tinderbox counter in the inventory. Tinderboxes can be used once to light a light source.

=== HandObject ===

Unused. Would have equipped the corresponding hand object on use.

== Chest ==

This is an unused feature, but it was kept in the engine and can be restored by making a custom entity. It is a object which can be opened using coins (or their replacements, if a custom Coin-type entity is made). Interacting with it brings up a text GUI. The text GUI can be changed in the base language file.
To make an entity of this type, just copy an existing entity file and change its entity type.
'''The chests that ended up in the game are actually just Levers.'''

{{warning|In versions before 1.5, Chests did not write their CoinsNeeded instance var to save data, which caused the coin requirement of all Chests to default to 0 when loading a save.}}

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CoinsNeeded || Int || 200 || Coins required to open the chest.
|-
|}

== OilBarrel ==

An OilBarrel entity simply adds some oil to the player's lantern upon interaction. The oil amount depends on the player's combined total oil stored in their lantern and as LampOil type items (the sum of the oil that the items would refill on use), determined when the player first looks at the OilBarrel. If the total oil is less than 100, the OilBarrel will contain exactly enough oil to bring it to 100. Otherwise (or if Hard Mode is enabled), it provides only 10 oil.

If the FullGameSave instance var is not enabled, OilBarrels can be used again when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| FillSound || File (.snt) || || Sound played when lantern is filled. Incorrectly defined as a string in EntityTypes.cfg.
|-
| EmptySound || File (.snt) || || Sound played when barrel is empty. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

== EmotionStone ==

The memory capsule entities found in the game. Interacting with an EmotionStone causes an emotion flash effect to display, fading the screen to white and displaying a message.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DescCat || String || || Category of text shown when in focus.
|-
| DescEntry || String || || Entry of text shown when in focus.
|-
| TextCat || String || || Category of text shown when interacted with. Typically "EmotionStone".
|-
| TextEntry || String || || Entry of text shown when interacted with.
|-
| Sound || File (.snt) || || Sound played when interacted with.
|-
|}

== NPC ==

Non-Player Characters are non-enemy characters. Agrippa and Alexander as they appear in-game are NPCs. Their only purpose is to stand in place and look at the player (if you enable the option).

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveHeadBones || String || || List of bones that is rotated when the NPC rotates its head.
|-
| MoveHeadBoneMuls || String || || List of floats specifying how much each bone shall be rotated (-1 to 1).
|-
| HeadMoveSpeedMul || Float || 1 || Speed multiplier that that determines move speed based on distance to wanted angle.
|-
| HeadMoveMaxSpeed || Float || 1 || The max speed that the head moves in.
|-
| MaxHeadAngle || Float || 30 || The max angle that the head can turn when looking at the player.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| FollowPlayerArea || String || || When player is in this area, the NPC will look at him.
|-
| Awake || Bool || true || If the NPC is awake and looks at the player when in area.
|-
|}

== LevelDoor ==

A LevelDoor transports the player to the specified level when interacted with. The locked sounds, text, and destination can be entered in the Level Editor itself.

LevelDoors can also teleport the player (without a loading screen) if the same map is picked.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| EnterSound || File (.snt) || || Sound played when entering door. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ExitSound || File (.snt) || || Sound played when entering new map after having interacted with door. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| TextEntry || String || || The text shown when door is in focus. Category is always Levels
|-
| StartPos || String || || The start position of the next map that the player is transported to.
|-
| MapFile || File (.map) || || The file of the next map.
|-
| Locked || Bool || false || If the door is locked.
|-
| LockedSound || File (.snt) || || Sound heard if locked and interacted with.
|-
| LockedTextCat || String || || Category of message shown if locked and interacted with.
|-
| LockedTextEntry || String || || Entry of message shown if locked and interacted with.
|-
| ShowStats || Bool || true || If stats of map it leads to should be shown (NOT IN USE) Non-functional. Formerly used to display a completion percentage.
|-
|}

== CritterBug ==

Critters like rats, roaches, or fish on the ground (or in the case of fish, water). They move around the room they are placed in and run away from the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MeshOffsetRot || Vector3 || 0 0 0 || The mesh offset rotation.
|-
| MeshOffsetPos || Vector3 || 0 0 0 || The mesh offset position.
|-
| MaxSpeedNormal || Float || 0.5 || Max speed when in normal state
|-
| MaxSpeedAfraid || Float || 1.3 || Max speed when in the scared state
|-
| Gravity || Float || 9.8 || Amount of gravity applied.
|-
| HasRandomPauses || Bool || false || If the critter shall have random pauses
|-
| RandomPauseTimeMinMax || Vector2 || 1 3 || Random time length of pause
|-
| RandomMoveTimeMinMax || Vector2 || 2 6 || Random time length of movement (between pauses)
|-
| PlayerFleeDistance || Float || 3 || The distance from player which it begins to flee
|-
| FleeMul || Float || 2.1 || Factor for moving away from player (if fleeing)
|-
| BackToSpawnPointMul || Float || 0.1 || Factor for moving back to spawn point
|-
| WanderCircleRadius || Float || 4 || Picture a circle in front critter at a certain distance. A point inside the circle is randomly selected and then the vector from the critter to this point is the speed added. The larger the circle, the more random the walk.
|-
| WanderCircleDist || Float || 2 || The distance at which the wander circle is placed. The higher the distance, the more likely the critter is to move forward.
|-
| NormalSound || File (.snt) || || Sound made when in normal state
|-
| NormalSoundRandMinMax || Vector2 || 1 3 || Random time length between normal sounds. x=min, y=max
|-
| ScaredSound || File (.snt) || || Sound made when in afraid state
|-
| ScaredSoundRandMinMax || Vector2 || 1 3 || Random time length between afraid sounds. x=min, y=max
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
|}

{{HPL2 InstanceVars Prop}}

== CritterSpider ==

A unused critter similar to the spider enemies from [[wikipedia:Penumbra: Overture|Penumbra: Overture]]. Capable of climbing walls and ceilings, as well as attacking the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MaxIdleSpeed || Float || 0.5 ||
|-
| MaxHuntSpeed || Float || 0.75 ||
|-
| HitSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSoundRandMinMax || Vector2 || 1 3 ||
|-
| AttackSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| AttackPlayerDistMinMax || Vector2 || 1 3 ||
|-
| HuntPlayerDist || Float || 8 ||
|-
| HuntTimeMinMax || Vector2 || 10 30 ||
|-
| MoveTimeMinMax || Vector2 || 4 8 ||
|-
| IdleTimeMinMax || Vector2 || 0.4 2 ||
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
| AttackSizeRadius || Float || 0.3 ||
|-
| AttackOffset || Vector3 || 0 0 1 ||
|-
| AttackDamageMinMax || Vector2 || 5 15 ||
|-
| AttackForce || Vector2 || 5 1 ||
|-
| AttackStrength || Int || 1 ||
|-
| AttackHitSound || File (.snt) || ||
|-
|}

{{HPL2 InstanceVars Prop}}

== Enemy_Grunt ==

An Enemy_Grunt entity is a standard enemy entity, used for the Grunt, Brute, and Suitor. Enemy entities require advanced setup, and should include animations added through Settings > Animations. Enemy properties can be modified in the entity type window, like certain sounds and music tracks playing, the enemy's awareness levels and damage, speed and other similar settings. An enemy does not use a collision box, but instead a skeleton and the aforementioned properties to determine how to collide/hit something.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 15 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 10 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 3.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 2.0 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 4.5 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.5 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 5 || The distance where the move toward enemy check starts
|-
| IdleExtraTimeMin || Float || 2 || Min time between extra idle animations
|-
| IdleExtraTimeMax || Float || 6 || Max time between extra idle animations
|-
| IdleExtraNum || Int || 3 || Number of extra idle animations
|-
|}

{{HPL2 InstanceVars Enemy}}

== Enemy_ManPig ==
{{clr}}
{{ReqVer|1.3}}

An enemy type ported from A Machine For Pigs. Compare to the [[HPL2/AMFP/NewEntities#Enemy_ManPig|AMFP version]] of the enemy.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| Quadruped_Walk_ForwardSpeed || Float || 1.0 || Forward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_BackwardSpeed || Float || 1.0 || Backward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_ForwardAcc || Float || 2.0 ||
|-
| Quadruped_Walk_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_Run_ForwardSpeed || Float || 3.0 || Forward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_BackwardSpeed || Float || 2.0 || Backward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_ForwardAcc || Float || 4.0 ||
|-
| Quadruped_Run_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_StoppedToWalkSpeed || Float || 0.05 || Speed at which the walk animation is played when on all fours
|-
| Quadruped_WalkToStoppedSpeed || Float || 0.02 || Speed at which walk goes to stopped when on all fours
|-
| Quadruped_WalkToRunSpeed || Float || 2.0 || Speed at which walk turns to run animation when on all fours
|-
| Quadruped_RunToWalkSpeed || Float || 0.9 || Speed at which run turns to walk when on all fours
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 1 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 6 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 2.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 0.5 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 1.0 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.25 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 6 || The distance where the move toward enemy check starts
|-
| IsTelsa || Bool || false || If this is the tesla pig
|-
| TeslaSoundLoop || File (.snt) || || Sound file played when the tesla's proximity effects are active. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ChaseSound || File (.snt) || || Played when the pig is chasing. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Instance Vars
! Name !! Type !! Default !! Description
|-
| Pose || String || Biped || The pose of the enemy to start with Can be "Biped" or "Quadruped".
|-
| ThreatenOnAlert || Bool || false || If the pig should stand still and threaten instead of walking towards player when in alert mode.
|-
| FleeFromPlayer || Bool || false || The pig will flee instead of hunting (threaten if ThreatenOnAlert). Disabled if far enough away. Will attack if cornered.
|-
| AutoDisableAfterFlee || Bool || false || If pig should be disabled after having fled (if possible)
|-
| LanternSensitivity || Float || 1 || A modifier for how quickly the pig reacts to being shined on by the lantern. Not defined in EntityTypes.cfg.
|-
| IdleBehavior || String || None || The behavior used when there are no patrol nodes left to walk. Can be "None", "Stalk", or "Track".
|-
| PlayActivateSound || Bool || true || If the enemy can play its EnabledSound.
|-
| AllowZeroNodeWaitTimes || Bool || false || If set to true, path node wait times with value 0 actually mean no waiting Normally, specifying a wait time of 0 in <code>AddEnemyPatrolNode</code> results in a wait time of 1-3 seconds.
|-
| PatrolMoveSpeed || String || Walk || Whether this pig walks or runs along its patrol Can be "Walk" or "Run".
|-
| DamageMul || Float || 1 || Multiplier for the enemy's attack damage. Not defined in EntityTypes.cfg.
|-
| RunSpeedMul || Float || 1 || Multiplier for the enemy's run speed. Not defined in EntityTypes.cfg.
|-
| HuntPauseTimeMul || Float || 1 || Multiplier for wait time between attacks.
|-
|}

== Enemy_Waterlurker ==

Enemy type of the "water monster". Since you can't assign animations to it, you might as well just use the normal waterlurker of the base game unless you want to change its properties (such as damage, movement speed, or music played).

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0.6 || The y-distance from the enemy that the player is detected.
|-
| EatDamage || Float || 20 || The damage dealt to food being eaten
|-
| AfterAttackPauseTime || Float || 0 || The amount of timer lurker waits after an attack
|-
| SplashPS_Walk || File (.ps) || || Particle system created at surface when walking.
|-
| SplashPS_Run || File (.ps) || || Particle system created at surface when running.
|-
| SplashPS_Eat || File (.ps) || || Particle system created at surface when eating.
|-
| SplashPS_Attack || File (.ps) || || Particle system created at surface when attacking.
|-
| SplashSound_Walk || File (.snt) || || Sound played when walking.
|-
| SplashSound_Run || File (.snt) || || Sound played when running.
|-
| SplashSound_Eat || File (.snt) || || Sound played when eating.
|-
| SplashSound_Attack || File (.snt) || || Sound played when attacking.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0 || If equal or below 0 the default in data file is used! The y-distance from the enemy that the player is detected.
|-
|}

== PlayerHands ==

Player's hands. Unless you want to make a different looking hand for a full conversion mod, you don't have to worry about this.

== HandObject ==

The only available HandObject is the lantern. It is used in conjunction with a <code>.ho</code> config file to place it properly in PlayerHands.

Mostly a remnant of cut items that functioned as weapons, like in [[wikipedia:Penumbra: Overture|Penumbra: Overture]], including the pickaxe from that game.

HPL2/TDD/Entity Types

2025-08-27T07:02:36Z

BoxFigs: /* Wheel */

{{TocRight}}

This page lists the different types of entities found within the HPL2 engine. The type determines how the entity will be set up, what kind it is, what it does under different circumstances etc. Using the Model Editor you can identify and specify which type an entity has and its type vars, in Settings > User defined variables. In the Level Editor, the different types have different settings applicable for them, known as instance vars. For example, a MoveObject type will have the OffsetArea box available in the Level Editor, and an Item (Note) type will have a NoteText box available.

A list of all the types and subtypes can be found in the table of contents to the right.

== StaticProp ==

A StaticProp entity resembles a static object. They have no available type properties, but they can still use physics bodies (collision boxes) and have mass/gravity. Note that they cannot be interacted with in the game, and cannot be disabled. If you need this feature, use Object (Static) instead.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CastShadows || Bool || true || If entity casts shadows.
|-
| IsAffectedByDecal || Bool || true || If decals can be created on entity.
|-
|}

== CommentaryIcon ==

A CommentaryIcon entity is simply an object that can execute commentary sound files, as it was done in the main game. These only appear if the player has "Commentary" enabled in their settings.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| RotateSubMesh || String || || The name of the submesh that is to be rotated
|-
|}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| File || File (.comment) || || The .comment file for the commentary.
|-
|}

== Object ==

Objects are entities that can be activated/deactivated, broken, and interact with physics.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| BreakActive || Bool || false || If entity is broken when hit hard enough or health is 0.
|-
| BreakDestroyJoints || Bool || false || If all physics joints should be destroyed when broken.
|-
| BreakMinEnergy || Float || 100 || The minimum energy needed for breakage. Energy = Object1Speed * Object1Mass + Object2Speed * Object2Mass. Speed = m/s. If Object 2 is floor or something static, its speed is always 0 and does not contribute to total energy!
|-
| BreakEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| BreakEntityAlignBody || String || || The body BreakEntity uses to align itself when created. No entity is created if left empty.
|-
| BreakSound || File (.snt) || || The sound made when broken.
|-
| BreakParticleSystem || File (.ps) || || Particle system shown when broken.
|-
| BreakImpulse || Float || 4 || Impulse (speed in m/s really) added to all bodies in BreakEntity when created. The direction of impulse is outwards from center of entity.
|-
| HitDamageAmount || Float || 5 || The amount of damage made when hitting an enemy or player.
|-
| HitDamageStrength || Int || 1 || The strength of the damage.
|-
| MinHitDamageSpeed || Float || 3 || The minimum speed (m/s) needed for damage to be made.
|-
| LifeLength || Float || 0 || A time after which the entity automatically breaks. 0=lasts forever.
|-
| IsFood || Bool || false || If this is food for some enemies and can be used to lure them. Needs to have break active and health determines how long the food lasts. Waterlurkers are the only enemy type that is lured by and eats food objects.
|-
| ShowHints || Bool || true || If a hint can be triggered by interacting with the prop.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| ContainedItem || String || None || An item that is created when entity breaks. Must match an entity file name (extension .ent optional) in the "items" folder.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
| IsInsanityVision || Bool || false || If the prop is only shown when insanity is low enough.
|-
| VisionMaxSanity || Float || 30 || The max sanity the player can have for prop to show if it is an insanity vision. The object will only be visible if the player's sanity is less than this value.
|-
|}

=== Static ===

Not to be confused with an actual static object. This Object subtype is a generic object with common properties. The static subtype simply disables any additional properties from the other subtypes. An Object (Static) is similar in concept to a StaticProp type entity, however the Object (Static) can be deactivated, can break, has physics, and can have an interact callback set.

=== Grab ===

A Grab subtype is a normal Object entity with the ability to be grabbed by the player in the game. In order for this to work, the object must have a mass above 0.

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| GrabUseDepth || Bool || false || If GrabDepth is used. If not the interaction distance is used.
|-
| GrabDepth || Float || 1.5 || The distance which a grabbed object is automatically placed at.
|-
| GrabDepthInc || Float || 0.15 || Steps that the entity will move in when moving the mouse scroll.
|-
| GrabMinDepth || Float || 1.0 || Minimum distance the entity can be from player when grabbed.
|-
| GrabMaxDepth || Float || 2.2 || Maximum distance the entity can be from player when grabbed.
|-
| GrabUseOffset || Bool || false || If rotation and position offset is used. If not offset will be relative to the interact position.
|-
| GrabPositionOffset || Vector3f || 0 || Positional offset of entity.
|-
| GrabRotationOffset || Vector3f || 0 || Rotational offset of entity. It will automatically rotate to this when grabbed.
|-
| GrabThrowImpulse || Float || 10 || The speed (m/s) at which the entity is thrown.
|-
| GrabMassMul || Float || 0.1 || How much the object will weight when grabbed. Useful for heavier objects since they can wreck mayhem otherwise. 0.5% means half (50%) of the original weight.
|-
| GrabForceMul || Float || 1 || Change how much force is added to grabbed object.
|-
| GrabTorqueMul || Float || 1 || Change how much torque is added to grabbed object.
|-
| GrabUseRotation || Bool || true || If rotation should be used on grabbed object
|-
| GrabSkipNonOuterBodies || Bool || false || If true, then bodies that are inside a chain (has two or more joints attached to it) will not be grabbed.
|-
|}

=== Push ===

Similar to the Grab subtype, the Push subtype allows the player to push the object by taking hold of it and walking or right clicking. Examples include large rocks and the bed covering the hole in the floor in the Prison - Southern Block.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| PushAtPoint || Bool || false || If the push force should be applied to the point at the object where interaction took place.
|-
| PushForceMul || Float || 1 || Multiplier for force applied. Used to fine tune interaction.
|-
| PushImpulse || Float || 2 || Impulse added when thrown.
|-
|}

=== Slide ===

A Slide Object is similar to the Grab subtype, except it can only be slid in a single direction for a certain amount. An existing (but unused) entity that uses this is the secret floor carpet you can slide to the side.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
|}

== SwingDoor ==

A SwingDoor entity is standard hinged door. Any door you can grab and swing open is considered a SwingDoor. To use a SwingDoor, you need to attach joints to where you want the door to swing around. These are usually placed by the hinges of the door. On the joint you can set the min and max values to limit how much the door can be opened. These are usually approximately 90 degrees apart in either positive or negative directions.

If the FullGameSave instance var is not enabled, SwingDoors will reset to their initial open amount when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the door is interacted with. Meaning that interacting with any part of the entity will work.
|-
| CloseOnSound || File (.snt) || || Sound played when the door is closed.
|-
| CloseOffSound || File (.snt) || || Sound played when the door is opened.
|-
| LockOnSound || File (.snt) || || Sound played when the door is locked.
|-
| LockOffSound || File (.snt) || || Sound played when the door is unlocked.
|-
| InteractLockedSound || File (.snt) || || Sound made when player interacts with a locked door.
|-
| Breakable || Bool || false || Can the door be broken.
|-
| DamageMesh1 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage1
|-
| DamageMesh2 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage2
|-
| BrokenEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| DamageSound || File (.snt) || || Sound made when a new damage mesh is used.
|-
| DamagePS || File (.ps) || || Particles created when a new damage mesh is used.
|-
| BreakSound || File (.snt) || || Sound made when broken.
|-
| BreakPS || File (.ps) || || Particles created when broken.
|-
| BreakImpulse || Float || 3 || Impulse set to objects in broken mesh. Incorrectly defined as a sound file in EntityTypes.cfg.
|-
| HealthDamage1 || Float || 66 || Health when damage mesh 1 is used.
|-
| HealthDamage2 || Float || 33 || Health when damage mesh 2 is used.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Locked || Bool || false || If the door is locked
|-
| OpenAmount || Float || 0 || The amount the door is open. 0 - 1.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
|}

== Lever ==

A Lever entity is an entity that can be swung between states to trigger callbacks. A lever requires a joint to swing around.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitSound || File (.snt) || || Sound played when at min limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MaxLimitSound || File (.snt) || || Sound played when at max limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MinLimitStuck || Bool || false || If the lever becomes stuck when reaching min. Missing from EntityTypes.cfg.
|-
| MaxLimitStuck || Bool || false || If the lever becomes stuck when reaching max. Missing from EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the position.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The initial stuck state for the lever. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

== Wheel ==

A Wheel entity is a wheel that can be turned. They use states similar to the levers. Some wheels can be turned indefinitely and some (mostly valves) can be turned for a fixed amount in order to trigger an event. Wheels require a joint.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the wheel is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
| MinLimitSound || File (.snt) || || Sound played at min limit
|-
| MaxLimitSound || File (.snt) || || Sound played at max limit
|-
| StuckSound || File (.snt) || || Sound played when stuck.
|-
| SlowDownRotation || Bool || true || If rotation should be slowed to 0 when not interacting.
|-
| SkipMiddleState || Bool || true || If the middle state (when not in max or min) should be skipped by script and connections.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
|}

== MultiSlider ==

A sliding-type lever that can be set to multiple states. Used for the gear levers in the Sewer.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
| NumOfStates || Int || 3 || The number of states used.
|-
| StickToStateMaxDist || Float || 0.1 || The distance from a state that the slider sticks.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| AutoMoveToCurrentState || Bool || true || If body should automove to current state when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the postion.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| ChangeStateSound || File (.snt) || || Sound played when state is changed Incorrectly defined as a string in EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| ChangeStateCallback || String || || Called when state changes Syntax: <code>void MyFunc(string &in asEntity, int alState)</code> Used instead of ConnectionStateChangeCallback, as this entity type can have more than two possible states.
|-
|}

== Lamp ==

A Lamp entity is a light source. If they are unlit, they can be lit by the player, consuming a tinderbox. Examples are torches and candles.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CanBeLitByPlayer || Bool || true || If the player can use a tinderbox on it to light it.
|-
| CanBeGrabbed || Bool || false || If it can be grabbed by the player. No effect. Presumably intended to make the entity behave like a Grab Object, yet this is unimplemented.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Lit || Bool || true || If the lamp is lit or not.
|-
| ConnectedLight || String || || Name of a light (that is not in an entity!) that will be connected to the this light and will increase/decrease in color as the lamp is turned on/off.
|-
| ConnectionLightAmount || Float || 1 || The amount to multiply the lamp's color by before adding it to the connected light's color.
|-
| ConnectionLightUseOnColor || Bool || true || If the on color should always be used. If false the light color (which might be flickering) is used.
|-
| ConnectionLightUseSpec || Bool || false || If the specular of the lamp color should be used.
|-
|}

== Button ==

A Button entity acts like a Lever, except it does not use a joint. It simply changes its connection state and toggles effects when interacted with.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| SwitchedOn || Bool || false || If the button starts as on or off
|-
| CanBeSwitchedOn || Bool || true || If player can switch it on.
|-
| CanBeSwitchedOff || Bool || false || If player can switch it off.
|-
|}

== Photocell ==

A prop that changes its texture illumination and connection state based on the light level around it. Presumably a leftover from Lux Tenebris, which featured light-based puzzles.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| LightLevelOnLimit || Float || 0.9 || Light level above this value turns the photocell on.
|-
| LightLevelOffLimit || Float || 0.1 || Light level below this value turns the photocell off.
|-
|}

== MoveObject ==

A MoveObject entity is an entity that can be specifically moved on a single axis through the use of scripting. It can be set to either Angular or Linear. Angular rotates the object around its own center point, unless otherwise specified by the use of an OffsetArea. Linear moves the object in a direction for a specified amount. Note that a linear move object can only move on one axis. You can pick X, Y, or Z in the entity and this cannot be changed mid-game. If you want the same object to move on more than 1 axis (for example left then forward) you can switch out the entity with an identical one that uses another axis. The script to move a MoveObject is <code>SetMoveObjectState</code> and <code>SetMoveObjectStateExt</code> (see [[HPL2/Engine Scripts|Engine Scripts]]).

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveObjectType || String || Linear || The way the object moves. Linear means position changes and Angular means rotation changes. Can be "Linear" or "Angular".
|-
| OpenAmount || Float || 1.0 || Linear: How much of the MoveAxis size that will mean that it is open. Angular: 1=90 degrees. 0.5=45deg and 2=180deg (any numbers inbetween are okay of course)
|-
| MoveAxis || String || X || he axis that the movement is about. For angular it is rotation axis and for linear it is the position axis that is changed. Can be "X", "Y", or "Z".
|-
| OpenAcc || Float || 5.0 || The acceleration for reaching OpenSpeed
|-
| OpenSpeed || Float || 1.0 || The goal speed when opening.
|-
| CloseAcc || Float || 5.0 || The acceleration for reaching CloseSpeed
|-
| CloseSpeed || Float || 1.0 || The goal speed when closing.
|-
| AutoMove || Bool || false || If the door should move towards some goal automatically.
|-
| AutoMoveStateGoal || Float || 0.0 || The amount (relative to the what is considered open) that it shall move towards.
|-
| AutoMoveAcc || Float || 9.0 || The acceleration when automoving
|-
| AutoMoveSpeed || Float || 5.0 || The goal speed when automoving
|-
| AutoMoveSlowdownDist || Float || 0.1 || The distance from state goal where it begins to slow down (in meters for linear and degrees for angular).
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| AngularOffsetArea || String || || When mode is angular, this the point it rotates around. If empty, it rotates around its center.
|-
|}

== Item ==

Item entities become inventory items when interacted with. They glow when in pickup range.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SubItemTypeName || String || || Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
| ImageFile || File (.tga/.dds/.jpg/.jpeg/.png) || || The icon shown in the inventory when picked up.
|-
| PickSound || String || Generic || The sound played when picked up. Must match a sound file name in the "ui" folder, starting with "pick_".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CustomSubItemTypeName || String || || If not emtpy it overrides SubItemTypeName in entity file. Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
|}

=== Puzzle ===

A Puzzle subtype item is a general item with no extra properties. Use this if you only need an inventory item to be used to trigger a scripted action. Other subtypes have special properties, but Puzzle only has the ability to be collected and used from the inventory. When used, it's loaded onto the crosshair so the player can use it on objects.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| TempVar || Float || 0 || User specfic usage.
|-
|}

=== Coins ===

Unused item type for the cut Thaler items. Thalers were once used to unlock Chests and use OilBarrels, with only the former functionality remaining.

{{warning|You can create custom coin items, but there is a single language entry which is hardcoded into the engine and can't be changed. This means that even if all the others are changed, looking at Chests will always say "Locked. Costs X Thalers to open."}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CoinAmount || Int || 10 || The amount of coins it contains.
|-
|}

=== Note ===

A Note item is an item that adds text to the player's journal. It displays itself when picked up. The note can be narrated, in which case it will automatically close once it's finished. If it isn't voiced, the player must close it. Use this if you want to make a Note item using a custom model or custom properties that differ from the main notes.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| NoteText || String || || The text and name of entry for note. Entry names for these are calculated: 'Note_'+NoteText+'_Name' and 'Note_'+NoteText+'_Text'
|-
| OpenNoteInJournal || Bool || true || If the journal should be opened when the note is picked up.
|-
| UseNarration || Bool || false || If the note has narration.
|-
|}

=== Diary ===

A Diary item is nearly identical to the Note item. Instead, it adds itself to the Diary section of the player's journal, whereas the Note adds itself to the Notes section. Additionally, diary entries are grouped together, so that when one is split into multiple parts, the player will always read them in order, regardless of the specific Diary items that were picked up.

Diaries are also always voice enabled, while Notes have the option for it. As such, a Diary without any voice files defined in its text will instantly close the journal on pickup.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DiaryText || String || || The text and name of entry for diary. Entry name for these calculated: 'Diary_'+DiaryText+'_Name'+Idx and 'Diary_'+DiaryText+'_Text'+Idx. Idx starts at 1.
|-
| DiaryCallback || String || || A special callback for diary pickup. Syntax: <code>void Func(string &in asItem, int lDiaryIdx)</code>. Call <code>ReturnOpenJournal(false)</code> to not open diary in journal after callback.
|-
|}

=== Lantern ===

A Lantern item can be picked up like a normal item, but is added as a lantern to the inventory. While having this item, the player can press F to toggle it, or click it in the inventory. Note: This is NOT the lantern model in the player's hands, only the item that gives it to the player. If you want a custom lantern model, you can follow [https://www.frictionalgames.com/forum/thread-12391.html this guide].

=== Health ===

A Health item acts like a health potion (Laudanum). It acts like a normal item, except when used it is consumed while increasing the player's health by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much health is regained when used.
|-
|}

=== Sanity ===

A Sanity item acts like a sanity potion. While used, they increase the player's sanity by a fixed amount, and then consumed from the inventory.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much sanity is regained when used.
|-
|}

=== LampOil ===

A LampOil item acts like an oil potion. When used, it increases the amount of oil for the lantern, and then consumed.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| OilAmount || Float || 25 || How much oil is regained when used.
|-
|}

=== Tinderbox ===

A Tinderbox item adds itself to the player's tinderbox counter in the inventory. Tinderboxes can be used once to light a light source.

=== HandObject ===

Unused. Would have equipped the corresponding hand object on use.

== Chest ==

This is an unused feature, but it was kept in the engine and can be restored by making a custom entity. It is a object which can be opened using coins (or their replacements, if a custom Coin-type entity is made). Interacting with it brings up a text GUI. The text GUI can be changed in the base language file.
To make an entity of this type, just copy an existing entity file and change its entity type.
'''The chests that ended up in the game are actually just Levers.'''

{{warning|In versions before 1.5, Chests did not write their CoinsNeeded instance var to save data, which caused the coin requirement of all Chests to default to 0 when loading a save.}}

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CoinsNeeded || Int || 200 || Coins required to open the chest.
|-
|}

== OilBarrel ==

An OilBarrel entity simply adds some oil to the player's lantern upon interaction. The oil amount depends on the player's combined total oil stored in their lantern and as LampOil type items (the sum of the oil that the items would refill on use), determined when the player first looks at the OilBarrel. If the total oil is less than 100, the OilBarrel will contain exactly enough oil to bring it to 100. Otherwise (or if Hard Mode is enabled), it provides only 10 oil.

If the FullGameSave instance var is not enabled, OilBarrels can be used again when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| FillSound || File (.snt) || || Sound played when lantern is filled. Incorrectly defined as a string in EntityTypes.cfg.
|-
| EmptySound || File (.snt) || || Sound played when barrel is empty. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

== EmotionStone ==

The memory capsule entities found in the game. Interacting with an EmotionStone causes an emotion flash effect to display, fading the screen to white and displaying a message.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DescCat || String || || Category of text shown when in focus.
|-
| DescEntry || String || || Entry of text shown when in focus.
|-
| TextCat || String || || Category of text shown when interacted with. Typically "EmotionStone".
|-
| TextEntry || String || || Entry of text shown when interacted with.
|-
| Sound || File (.snt) || || Sound played when interacted with.
|-
|}

== NPC ==

Non-Player Characters are non-enemy characters. Agrippa and Alexander as they appear in-game are NPCs. Their only purpose is to stand in place and look at the player (if you enable the option).

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveHeadBones || String || || List of bones that is rotated when the NPC rotates its head.
|-
| MoveHeadBoneMuls || String || || List of floats specifying how much each bone shall be rotated (-1 to 1).
|-
| HeadMoveSpeedMul || Float || 1 || Speed multiplier that that determines move speed based on distance to wanted angle.
|-
| HeadMoveMaxSpeed || Float || 1 || The max speed that the head moves in.
|-
| MaxHeadAngle || Float || 30 || The max angle that the head can turn when looking at the player.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| FollowPlayerArea || String || || When player is in this area, the NPC will look at him.
|-
| Awake || Bool || true || If the NPC is awake and looks at the player when in area.
|-
|}

== LevelDoor ==

A LevelDoor transports the player to the specified level when interacted with. The locked sounds, text, and destination can be entered in the Level Editor itself.

LevelDoors can also teleport the player (without a loading screen) if the same map is picked.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| EnterSound || File (.snt) || || Sound played when entering door. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ExitSound || File (.snt) || || Sound played when entering new map after having interacted with door. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| TextEntry || String || || The text shown when door is in focus. Category is always Levels
|-
| StartPos || String || || The start position of the next map that the player is transported to.
|-
| MapFile || File (.map) || || The file of the next map.
|-
| Locked || Bool || false || If the door is locked.
|-
| LockedSound || File (.snt) || || Sound heard if locked and interacted with.
|-
| LockedTextCat || String || || Category of message shown if locked and interacted with.
|-
| LockedTextEntry || String || || Entry of message shown if locked and interacted with.
|-
| ShowStats || Bool || true || If stats of map it leads to should be shown (NOT IN USE) Non-functional. Formerly used to display a completion percentage.
|-
|}

== CritterBug ==

Critters like rats, roaches, or fish on the ground (or in the case of fish, water). They move around the room they are placed in and run away from the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MeshOffsetRot || Vector3 || 0 0 0 || The mesh offset rotation.
|-
| MeshOffsetPos || Vector3 || 0 0 0 || The mesh offset position.
|-
| MaxSpeedNormal || Float || 0.5 || Max speed when in normal state
|-
| MaxSpeedAfraid || Float || 1.3 || Max speed when in the scared state
|-
| Gravity || Float || 9.8 || Amount of gravity applied.
|-
| HasRandomPauses || Bool || false || If the critter shall have random pauses
|-
| RandomPauseTimeMinMax || Vector2 || 1 3 || Random time length of pause
|-
| RandomMoveTimeMinMax || Vector2 || 2 6 || Random time length of movement (between pauses)
|-
| PlayerFleeDistance || Float || 3 || The distance from player which it begins to flee
|-
| FleeMul || Float || 2.1 || Factor for moving away from player (if fleeing)
|-
| BackToSpawnPointMul || Float || 0.1 || Factor for moving back to spawn point
|-
| WanderCircleRadius || Float || 4 || Picture a circle in front critter at a certain distance. A point inside the circle is randomly selected and then the vector from the critter to this point is the speed added. The larger the circle, the more random the walk.
|-
| WanderCircleDist || Float || 2 || The distance at which the wander circle is placed. The higher the distance, the more likely the critter is to move forward.
|-
| NormalSound || File (.snt) || || Sound made when in normal state
|-
| NormalSoundRandMinMax || Vector2 || 1 3 || Random time length between normal sounds. x=min, y=max
|-
| ScaredSound || File (.snt) || || Sound made when in afraid state
|-
| ScaredSoundRandMinMax || Vector2 || 1 3 || Random time length between afraid sounds. x=min, y=max
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
|}

{{HPL2 InstanceVars Prop}}

== CritterSpider ==

A unused critter similar to the spider enemies from [[wikipedia:Penumbra: Overture|Penumbra: Overture]]. Capable of climbing walls and ceilings, as well as attacking the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MaxIdleSpeed || Float || 0.5 ||
|-
| MaxHuntSpeed || Float || 0.75 ||
|-
| HitSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSoundRandMinMax || Vector2 || 1 3 ||
|-
| AttackSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| AttackPlayerDistMinMax || Vector2 || 1 3 ||
|-
| HuntPlayerDist || Float || 8 ||
|-
| HuntTimeMinMax || Vector2 || 10 30 ||
|-
| MoveTimeMinMax || Vector2 || 4 8 ||
|-
| IdleTimeMinMax || Vector2 || 0.4 2 ||
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
| AttackSizeRadius || Float || 0.3 ||
|-
| AttackOffset || Vector3 || 0 0 1 ||
|-
| AttackDamageMinMax || Vector2 || 5 15 ||
|-
| AttackForce || Vector2 || 5 1 ||
|-
| AttackStrength || Int || 1 ||
|-
| AttackHitSound || File (.snt) || ||
|-
|}

{{HPL2 InstanceVars Prop}}

== Enemy_Grunt ==

An Enemy_Grunt entity is a standard enemy entity, used for the Grunt, Brute, and Suitor. Enemy entities require advanced setup, and should include animations added through Settings > Animations. Enemy properties can be modified in the entity type window, like certain sounds and music tracks playing, the enemy's awareness levels and damage, speed and other similar settings. An enemy does not use a collision box, but instead a skeleton and the aforementioned properties to determine how to collide/hit something.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 15 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 10 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 3.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 2.0 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 4.5 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.5 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 5 || The distance where the move toward enemy check starts
|-
| IdleExtraTimeMin || Float || 2 || Min time between extra idle animations
|-
| IdleExtraTimeMax || Float || 6 || Max time between extra idle animations
|-
| IdleExtraNum || Int || 3 || Number of extra idle animations
|-
|}

{{HPL2 InstanceVars Enemy}}

== Enemy_ManPig ==
{{clr}}
{{ReqVer|1.3}}

An enemy type ported from A Machine For Pigs. Compare to the [[HPL2/AMFP/NewEntities#Enemy_ManPig|AMFP version]] of the enemy.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| Quadruped_Walk_ForwardSpeed || Float || 1.0 || Forward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_BackwardSpeed || Float || 1.0 || Backward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_ForwardAcc || Float || 2.0 ||
|-
| Quadruped_Walk_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_Run_ForwardSpeed || Float || 3.0 || Forward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_BackwardSpeed || Float || 2.0 || Backward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_ForwardAcc || Float || 4.0 ||
|-
| Quadruped_Run_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_StoppedToWalkSpeed || Float || 0.05 || Speed at which the walk animation is played when on all fours
|-
| Quadruped_WalkToStoppedSpeed || Float || 0.02 || Speed at which walk goes to stopped when on all fours
|-
| Quadruped_WalkToRunSpeed || Float || 2.0 || Speed at which walk turns to run animation when on all fours
|-
| Quadruped_RunToWalkSpeed || Float || 0.9 || Speed at which run turns to walk when on all fours
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 1 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 6 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 2.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 0.5 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 1.0 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.25 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 6 || The distance where the move toward enemy check starts
|-
| IsTelsa || Bool || false || If this is the tesla pig
|-
| TeslaSoundLoop || File (.snt) || || Sound file played when the tesla's proximity effects are active. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ChaseSound || File (.snt) || || Played when the pig is chasing. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Instance Vars
! Name !! Type !! Default !! Description
|-
| Pose || String || Biped || The pose of the enemy to start with Can be "Biped" or "Quadruped".
|-
| ThreatenOnAlert || Bool || false || If the pig should stand still and threaten instead of walking towards player when in alert mode.
|-
| FleeFromPlayer || Bool || false || The pig will flee instead of hunting (threaten if ThreatenOnAlert). Disabled if far enough away. Will attack if cornered.
|-
| AutoDisableAfterFlee || Bool || false || If pig should be disabled after having fled (if possible)
|-
| LanternSensitivity || Float || 1 || A modifier for how quickly the pig reacts to being shined on by the lantern. Not defined in EntityTypes.cfg.
|-
| IdleBehavior || String || None || The behavior used when there are no patrol nodes left to walk. Can be "None", "Stalk", or "Track".
|-
| PlayActivateSound || Bool || true || If the enemy can play its EnabledSound.
|-
| AllowZeroNodeWaitTimes || Bool || false || If set to true, path node wait times with value 0 actually mean no waiting Normally, specifying a wait time of 0 in <code>AddEnemyPatrolNode</code> results in a wait time of 1-3 seconds.
|-
| PatrolMoveSpeed || String || Walk || Whether this pig walks or runs along its patrol Can be "Walk" or "Run".
|-
| DamageMul || Float || 1 || Multiplier for the enemy's attack damage. Not defined in EntityTypes.cfg.
|-
| RunSpeedMul || Float || 1 || Multiplier for the enemy's run speed. Not defined in EntityTypes.cfg.
|-
| HuntPauseTimeMul || Float || 1 || Multiplier for wait time between attacks.
|-
|}

== Enemy_Waterlurker ==

Enemy type of the "water monster". Since you can't assign animations to it, you might as well just use the normal waterlurker of the base game unless you want to change its properties (such as damage, movement speed, or music played).

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0.6 || The y-distance from the enemy that the player is detected.
|-
| EatDamage || Float || 20 || The damage dealt to food being eaten
|-
| AfterAttackPauseTime || Float || 0 || The amount of timer lurker waits after an attack
|-
| SplashPS_Walk || File (.ps) || || Particle system created at surface when walking.
|-
| SplashPS_Run || File (.ps) || || Particle system created at surface when running.
|-
| SplashPS_Eat || File (.ps) || || Particle system created at surface when eating.
|-
| SplashPS_Attack || File (.ps) || || Particle system created at surface when attacking.
|-
| SplashSound_Walk || File (.snt) || || Sound played when walking.
|-
| SplashSound_Run || File (.snt) || || Sound played when running.
|-
| SplashSound_Eat || File (.snt) || || Sound played when eating.
|-
| SplashSound_Attack || File (.snt) || || Sound played when attacking.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0 || If equal or below 0 the default in data file is used! The y-distance from the enemy that the player is detected.
|-
|}

== PlayerHands ==

Player's hands. Unless you want to make a different looking hand for a full conversion mod, you don't have to worry about this.

== HandObject ==

The only available HandObject is the lantern. It is used in conjunction with a <code>.ho</code> config file to place it properly in PlayerHands.

Mostly a remnant of cut items that functioned as weapons, like in [[wikipedia:Penumbra: Overture|Penumbra: Overture]], including the pickaxe from that game.

HPL2/Engine Scripts

2025-08-27T04:22:42Z

BoxFigs: /* Levers, wheels and buttons */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<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 &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<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 &in 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 &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in asName, int alState, bool abEffects);
</syntaxhighlight>

Makes an object/wheel/lever stuck in a certain state.

#''asName'' - internal name
#''alState'' - 0 = not stuck, 1 = at max, -1 = at min
#''abEffects'' - play sound effects

<syntaxhighlight lang="cpp">
void SetWheelAngle(string &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/TDD/Entity Types

2025-04-15T18:50:33Z

BoxFigs: /* MoveObject */

{{TocRight}}

This page lists the different types of entities found within the HPL2 engine. The type determines how the entity will be set up, what kind it is, what it does under different circumstances etc. Using the Model Editor you can identify and specify which type an entity has and its type vars, in Settings > User defined variables. In the Level Editor, the different types have different settings applicable for them, known as instance vars. For example, a MoveObject type will have the OffsetArea box available in the Level Editor, and an Item (Note) type will have a NoteText box available.

A list of all the types and subtypes can be found in the table of contents to the right.

== StaticProp ==

A StaticProp entity resembles a static object. They have no available type properties, but they can still use physics bodies (collision boxes) and have mass/gravity. Note that they cannot be interacted with in the game, and cannot be disabled. If you need this feature, use Object (Static) instead.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CastShadows || Bool || true || If entity casts shadows.
|-
| IsAffectedByDecal || Bool || true || If decals can be created on entity.
|-
|}

== CommentaryIcon ==

A CommentaryIcon entity is simply an object that can execute commentary sound files, as it was done in the main game. These only appear if the player has "Commentary" enabled in their settings.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| RotateSubMesh || String || || The name of the submesh that is to be rotated
|-
|}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| File || File (.comment) || || The .comment file for the commentary.
|-
|}

== Object ==

Objects are entities that can be activated/deactivated, broken, and interact with physics.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| BreakActive || Bool || false || If entity is broken when hit hard enough or health is 0.
|-
| BreakDestroyJoints || Bool || false || If all physics joints should be destroyed when broken.
|-
| BreakMinEnergy || Float || 100 || The minimum energy needed for breakage. Energy = Object1Speed * Object1Mass + Object2Speed * Object2Mass. Speed = m/s. If Object 2 is floor or something static, its speed is always 0 and does not contribute to total energy!
|-
| BreakEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| BreakEntityAlignBody || String || || The body BreakEntity uses to align itself when created. No entity is created if left empty.
|-
| BreakSound || File (.snt) || || The sound made when broken.
|-
| BreakParticleSystem || File (.ps) || || Particle system shown when broken.
|-
| BreakImpulse || Float || 4 || Impulse (speed in m/s really) added to all bodies in BreakEntity when created. The direction of impulse is outwards from center of entity.
|-
| HitDamageAmount || Float || 5 || The amount of damage made when hitting an enemy or player.
|-
| HitDamageStrength || Int || 1 || The strength of the damage.
|-
| MinHitDamageSpeed || Float || 3 || The minimum speed (m/s) needed for damage to be made.
|-
| LifeLength || Float || 0 || A time after which the entity automatically breaks. 0=lasts forever.
|-
| IsFood || Bool || false || If this is food for some enemies and can be used to lure them. Needs to have break active and health determines how long the food lasts. Waterlurkers are the only enemy type that is lured by and eats food objects.
|-
| ShowHints || Bool || true || If a hint can be triggered by interacting with the prop.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| ContainedItem || String || None || An item that is created when entity breaks. Must match an entity file name (extension .ent optional) in the "items" folder.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
| IsInsanityVision || Bool || false || If the prop is only shown when insanity is low enough.
|-
| VisionMaxSanity || Float || 30 || The max sanity the player can have for prop to show if it is an insanity vision. The object will only be visible if the player's sanity is less than this value.
|-
|}

=== Static ===

Not to be confused with an actual static object. This Object subtype is a generic object with common properties. The static subtype simply disables any additional properties from the other subtypes. An Object (Static) is similar in concept to a StaticProp type entity, however the Object (Static) can be deactivated, can break, has physics, and can have an interact callback set.

=== Grab ===

A Grab subtype is a normal Object entity with the ability to be grabbed by the player in the game. In order for this to work, the object must have a mass above 0.

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| GrabUseDepth || Bool || false || If GrabDepth is used. If not the interaction distance is used.
|-
| GrabDepth || Float || 1.5 || The distance which a grabbed object is automatically placed at.
|-
| GrabDepthInc || Float || 0.15 || Steps that the entity will move in when moving the mouse scroll.
|-
| GrabMinDepth || Float || 1.0 || Minimum distance the entity can be from player when grabbed.
|-
| GrabMaxDepth || Float || 2.2 || Maximum distance the entity can be from player when grabbed.
|-
| GrabUseOffset || Bool || false || If rotation and position offset is used. If not offset will be relative to the interact position.
|-
| GrabPositionOffset || Vector3f || 0 || Positional offset of entity.
|-
| GrabRotationOffset || Vector3f || 0 || Rotational offset of entity. It will automatically rotate to this when grabbed.
|-
| GrabThrowImpulse || Float || 10 || The speed (m/s) at which the entity is thrown.
|-
| GrabMassMul || Float || 0.1 || How much the object will weight when grabbed. Useful for heavier objects since they can wreck mayhem otherwise. 0.5% means half (50%) of the original weight.
|-
| GrabForceMul || Float || 1 || Change how much force is added to grabbed object.
|-
| GrabTorqueMul || Float || 1 || Change how much torque is added to grabbed object.
|-
| GrabUseRotation || Bool || true || If rotation should be used on grabbed object
|-
| GrabSkipNonOuterBodies || Bool || false || If true, then bodies that are inside a chain (has two or more joints attached to it) will not be grabbed.
|-
|}

=== Push ===

Similar to the Grab subtype, the Push subtype allows the player to push the object by taking hold of it and walking or right clicking. Examples include large rocks and the bed covering the hole in the floor in the Prison - Southern Block.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| PushAtPoint || Bool || false || If the push force should be applied to the point at the object where interaction took place.
|-
| PushForceMul || Float || 1 || Multiplier for force applied. Used to fine tune interaction.
|-
| PushImpulse || Float || 2 || Impulse added when thrown.
|-
|}

=== Slide ===

A Slide Object is similar to the Grab subtype, except it can only be slid in a single direction for a certain amount. An existing (but unused) entity that uses this is the secret floor carpet you can slide to the side.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
|}

== SwingDoor ==

A SwingDoor entity is standard hinged door. Any door you can grab and swing open is considered a SwingDoor. To use a SwingDoor, you need to attach joints to where you want the door to swing around. These are usually placed by the hinges of the door. On the joint you can set the min and max values to limit how much the door can be opened. These are usually approximately 90 degrees apart in either positive or negative directions.

If the FullGameSave instance var is not enabled, SwingDoors will reset to their initial open amount when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the door is interacted with. Meaning that interacting with any part of the entity will work.
|-
| CloseOnSound || File (.snt) || || Sound played when the door is closed.
|-
| CloseOffSound || File (.snt) || || Sound played when the door is opened.
|-
| LockOnSound || File (.snt) || || Sound played when the door is locked.
|-
| LockOffSound || File (.snt) || || Sound played when the door is unlocked.
|-
| InteractLockedSound || File (.snt) || || Sound made when player interacts with a locked door.
|-
| Breakable || Bool || false || Can the door be broken.
|-
| DamageMesh1 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage1
|-
| DamageMesh2 || File (.dae/.msh/.mesh) || || Mesh used when health is below HealthDamage2
|-
| BrokenEntity || File (.ent) || || The entity this entity turns into when broken.
|-
| DamageSound || File (.snt) || || Sound made when a new damage mesh is used.
|-
| DamagePS || File (.ps) || || Particles created when a new damage mesh is used.
|-
| BreakSound || File (.snt) || || Sound made when broken.
|-
| BreakPS || File (.ps) || || Particles created when broken.
|-
| BreakImpulse || Float || 3 || Impulse set to objects in broken mesh. Incorrectly defined as a sound file in EntityTypes.cfg.
|-
| HealthDamage1 || Float || 66 || Health when damage mesh 1 is used.
|-
| HealthDamage2 || Float || 33 || Health when damage mesh 2 is used.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Locked || Bool || false || If the door is locked
|-
| OpenAmount || Float || 0 || The amount the door is open. 0 - 1.
|-
| DisableBreakable || Bool || false || If the entity is breakable then having this true will make it unbreakable.
|-
|}

== Lever ==

A Lever entity is an entity that can be swung between states to trigger callbacks. A lever requires a joint to swing around.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitSound || File (.snt) || || Sound played when at min limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MaxLimitSound || File (.snt) || || Sound played when at max limit Incorrectly defined as a string in EntityTypes.cfg.
|-
| MinLimitStuck || Bool || false || If the lever becomes stuck when reaching min. Missing from EntityTypes.cfg.
|-
| MaxLimitStuck || Bool || false || If the lever becomes stuck when reaching max. Missing from EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the position.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The initial stuck state for the lever. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MiddleAngleAmount || Float || 0 || The amount between min and max that is considered middle. -1 to 1. -1=at min, 0=exactly between min and max, 1=at max
|-
| AutoMoveToAngle || Bool || True || If the lever should move to position when not interacted with.
|-
| AutoMoveGoal || String || Middle || Where it should go when auto moving. Can be "Middle", "Min", or "Max".
|-
|}

== Wheel ==

A Wheel entity is a wheel that can be turned. They use states similar to the levers. Some wheels can be turned indefinitely and some (mostly valves) can be turned for a fixed amount in order to trigger an event. Wheels require a joint.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the wheel is interacted with. Meaning that interacting with any part of the entity will work.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitRange || Float || 5.0 || The distance from min the joint can be to be considered at min limit.
|-
| MaxLimitRange || Float || 5.0 || The distance from max the joint can be to be considered at max limit.
|-
| MinLimitStuck || Bool || false || If the wheel becomes stuck when reaching min limit.
|-
| MaxLimitStuck || Bool || false || If the wheel becomes stuck when reaching max limit.
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
| MinLimitSound || File (.snt) || || Sound played at min limit
|-
| MaxLimitSound || File (.snt) || || Sound played at max limit
|-
| StuckSound || File (.snt) || || Sound played when stuck.
|-
| SlowDownRotation || Bool || true || If rotation should be slowed to 0 when not interacting.
|-
| SkipMiddleState || Bool || true || If the middle state (when not in max or min) should be skipped by script and connections.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| OverrideDefaults || Bool || false || If normal settings, set in ent file, should be overridden by settings below.
|-
| MinLimit || Float || -180 || Min limit of the wheel, should be equal or below 0 but can be as low as wanted. Several revolutions are supported!
|-
| MaxLimit || Float || 180 || Max limit of the wheel, should be equal or above 0 but can be as high as wanted. Several revolutions are supported!
|-
| MinLimitStuck || Bool || false || If stuck at min limit
|-
| MaxLimitStuck || Bool || false || If stuck at max limit
|-
| SpinDir || String || BothWays || The direction the wheel can be spun Can be "BothWays", "ToMin", or "ToMax".
|-
|}

== MultiSlider ==

A sliding-type lever that can be set to multiple states. Used for the gear levers in the Sewer.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| SlideMaxSpeed || Float || 10 || The maximum speed it can be moved.
|-
| SlideSlowDownFactor || Float || 1 || Amount of slowdown applied to object when not moved.
|-
| SlideSpeedFactor || Float || 1 || The higher value the more speed gain a mouse movement makes.
|-
| SlideThrowImpulse || Float || 3 || Impulse added when thrown.
|-
| NumOfStates || Int || 3 || The number of states used.
|-
| StickToStateMaxDist || Float || 0.1 || The distance from a state that the slider sticks.
|-
| CanInteractWithStaticBody || Bool || false || If by interacting with a static body in the entity, the lever is interacted with. Meaning that interacting with any part of the entity will work.
|-
| AutoMoveToCurrentState || Bool || true || If body should automove to current state when not interacted with.
|-
| AutoMoveSpeedFactor || Float || 2 || Multiplier applied to speed to determine the speed it moves towards wanted position. The higher the faster it gets to the postion.
|-
| AutoMoveMaxSpeed || Float || 8 || Max speed it can move at to the wanted position
|-
| ChangeStateSound || File (.snt) || || Sound played when state is changed Incorrectly defined as a string in EntityTypes.cfg.
|-
| StuckSound || File (.snt) || || Sound played when stuck Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| StuckState || String || None || The stuck state for the wheel. Can be "None", "Min", or "Max".
|-
| InteractionDisablesStuck || Bool || false || If stuck is disabled when player interacts.
|-
| ChangeStateCallback || String || || Called when state changes Syntax: <code>void MyFunc(string &in asEntity, int alState)</code> Used instead of ConnectionStateChangeCallback, as this entity type can have more than two possible states.
|-
|}

== Lamp ==

A Lamp entity is a light source. If they are unlit, they can be lit by the player, consuming a tinderbox. Examples are torches and candles.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CanBeLitByPlayer || Bool || true || If the player can use a tinderbox on it to light it.
|-
| CanBeGrabbed || Bool || false || If it can be grabbed by the player. No effect. Presumably intended to make the entity behave like a Grab Object, yet this is unimplemented.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| Lit || Bool || true || If the lamp is lit or not.
|-
| ConnectedLight || String || || Name of a light (that is not in an entity!) that will be connected to the this light and will increase/decrease in color as the lamp is turned on/off.
|-
| ConnectionLightAmount || Float || 1 || The amount to multiply the lamp's color by before adding it to the connected light's color.
|-
| ConnectionLightUseOnColor || Bool || true || If the on color should always be used. If false the light color (which might be flickering) is used.
|-
| ConnectionLightUseSpec || Bool || false || If the specular of the lamp color should be used.
|-
|}

== Button ==

A Button entity acts like a Lever, except it does not use a joint. It simply changes its connection state and toggles effects when interacted with.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| SwitchedOn || Bool || false || If the button starts as on or off
|-
| CanBeSwitchedOn || Bool || true || If player can switch it on.
|-
| CanBeSwitchedOff || Bool || false || If player can switch it off.
|-
|}

== Photocell ==

A prop that changes its texture illumination and connection state based on the light level around it. Presumably a leftover from Lux Tenebris, which featured light-based puzzles.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| LightLevelOnLimit || Float || 0.9 || Light level above this value turns the photocell on.
|-
| LightLevelOffLimit || Float || 0.1 || Light level below this value turns the photocell off.
|-
|}

== MoveObject ==

A MoveObject entity is an entity that can be specifically moved on a single axis through the use of scripting. It can be set to either Angular or Linear. Angular rotates the object around its own center point, unless otherwise specified by the use of an OffsetArea. Linear moves the object in a direction for a specified amount. Note that a linear move object can only move on one axis. You can pick X, Y, or Z in the entity and this cannot be changed mid-game. If you want the same object to move on more than 1 axis (for example left then forward) you can switch out the entity with an identical one that uses another axis. The script to move a MoveObject is <code>SetMoveObjectState</code> and <code>SetMoveObjectStateExt</code> (see [[HPL2/Engine Scripts|Engine Scripts]]).

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MoveObjectType || String || Linear || The way the object moves. Linear means position changes and Angular means rotation changes. Can be "Linear" or "Angular".
|-
| OpenAmount || Float || 1.0 || Linear: How much of the MoveAxis size that will mean that it is open. Angular: 1=90 degrees. 0.5=45deg and 2=180deg (any numbers inbetween are okay of course)
|-
| MoveAxis || String || X || he axis that the movement is about. For angular it is rotation axis and for linear it is the position axis that is changed. Can be "X", "Y", or "Z".
|-
| OpenAcc || Float || 5.0 || The acceleration for reaching OpenSpeed
|-
| OpenSpeed || Float || 1.0 || The goal speed when opening.
|-
| CloseAcc || Float || 5.0 || The acceleration for reaching CloseSpeed
|-
| CloseSpeed || Float || 1.0 || The goal speed when closing.
|-
| AutoMove || Bool || false || If the door should move towards some goal automatically.
|-
| AutoMoveStateGoal || Float || 0.0 || The amount (relative to the what is considered open) that it shall move towards.
|-
| AutoMoveAcc || Float || 9.0 || The acceleration when automoving
|-
| AutoMoveSpeed || Float || 5.0 || The goal speed when automoving
|-
| AutoMoveSlowdownDist || Float || 0.1 || The distance from state goal where it begins to slow down (in meters for linear and degrees for angular).
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| AngularOffsetArea || String || || When mode is angular, this the point it rotates around. If empty, it rotates around its center.
|-
|}

== Item ==

Item entities become inventory items when interacted with. They glow when in pickup range.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| SubItemTypeName || String || || Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
| ImageFile || File (.tga/.dds/.jpg/.jpeg/.png) || || The icon shown in the inventory when picked up.
|-
| PickSound || String || Generic || The sound played when picked up. Must match a sound file name in the "ui" folder, starting with "pick_".
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CustomSubItemTypeName || String || || If not emtpy it overrides SubItemTypeName in entity file. Determines its name and description by putting 'ItemDesc_' or 'ItemName_' as prefix for the lang file entry. Category is always Inventory
|-
|}

=== Puzzle ===

A Puzzle subtype item is a general item with no extra properties. Use this if you only need an inventory item to be used to trigger a scripted action. Other subtypes have special properties, but Puzzle only has the ability to be collected and used from the inventory. When used, it's loaded onto the crosshair so the player can use it on objects.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| TempVar || Float || 0 || User specfic usage.
|-
|}

=== Coins ===

Unused item type for the cut Thaler items. Thalers were once used to unlock Chests and use OilBarrels, with only the former functionality remaining.

{{warning|You can create custom coin items, but there is a single language entry which is hardcoded into the engine and can't be changed. This means that even if all the others are changed, looking at Chests will always say "Locked. Costs X Thalers to open."}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| CoinAmount || Int || 10 || The amount of coins it contains.
|-
|}

=== Note ===

A Note item is an item that adds text to the player's journal. It displays itself when picked up. The note can be narrated, in which case it will automatically close once it's finished. If it isn't voiced, the player must close it. Use this if you want to make a Note item using a custom model or custom properties that differ from the main notes.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| NoteText || String || || The text and name of entry for note. Entry names for these are calculated: 'Note_'+NoteText+'_Name' and 'Note_'+NoteText+'_Text'
|-
| OpenNoteInJournal || Bool || true || If the journal should be opened when the note is picked up.
|-
| UseNarration || Bool || false || If the note has narration.
|-
|}

=== Diary ===

A Diary item is nearly identical to the Note item. Instead, it adds itself to the Diary section of the player's journal, whereas the Note adds itself to the Notes section. Additionally, diary entries are grouped together, so that when one is split into multiple parts, the player will always read them in order, regardless of the specific Diary items that were picked up.

Diaries are also always voice enabled, while Notes have the option for it. As such, a Diary without any voice files defined in its text will instantly close the journal on pickup.

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DiaryText || String || || The text and name of entry for diary. Entry name for these calculated: 'Diary_'+DiaryText+'_Name'+Idx and 'Diary_'+DiaryText+'_Text'+Idx. Idx starts at 1.
|-
| DiaryCallback || String || || A special callback for diary pickup. Syntax: <code>void Func(string &in asItem, int lDiaryIdx)</code>. Call <code>ReturnOpenJournal(false)</code> to not open diary in journal after callback.
|-
|}

=== Lantern ===

A Lantern item can be picked up like a normal item, but is added as a lantern to the inventory. While having this item, the player can press F to toggle it, or click it in the inventory. Note: This is NOT the lantern model in the player's hands, only the item that gives it to the player. If you want a custom lantern model, you can follow [https://www.frictionalgames.com/forum/thread-12391.html this guide].

=== Health ===

A Health item acts like a health potion (Laudanum). It acts like a normal item, except when used it is consumed while increasing the player's health by a specified amount.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much health is regained when used.
|-
|}

=== Sanity ===

A Sanity item acts like a sanity potion. While used, they increase the player's sanity by a fixed amount, and then consumed from the inventory.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| HealAmount || Float || 25 || How much sanity is regained when used.
|-
|}

=== LampOil ===

A LampOil item acts like an oil potion. When used, it increases the amount of oil for the lantern, and then consumed.

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| OilAmount || Float || 25 || How much oil is regained when used.
|-
|}

=== Tinderbox ===

A Tinderbox item adds itself to the player's tinderbox counter in the inventory. Tinderboxes can be used once to light a light source.

=== HandObject ===

Unused. Would have equipped the corresponding hand object on use.

== Chest ==

This is an unused feature, but it was kept in the engine and can be restored by making a custom entity. It is a object which can be opened using coins (or their replacements, if a custom Coin-type entity is made). Interacting with it brings up a text GUI. The text GUI can be changed in the base language file.
To make an entity of this type, just copy an existing entity file and change its entity type.
'''The chests that ended up in the game are actually just Levers.'''

{{warning|In versions before 1.5, Chests did not write their CoinsNeeded instance var to save data, which caused the coin requirement of all Chests to default to 0 when loading a save.}}

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveMaxSpeed || Float || 13.5 || The maximum speed it can be moved.
|-
| MoveSlowDownFactor || Float || 3.0 || Amount of slowdown applied to object when not moved.
|-
| MoveSpeedFactor || Float || 1.0 || The higher value the more speed gain a mouse movement makes.
|-
| MoveThrowImpulse || Float || 6.0 || Impulse added when thrown.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| CoinsNeeded || Int || 200 || Coins required to open the chest.
|-
|}

== OilBarrel ==

An OilBarrel entity simply adds some oil to the player's lantern upon interaction. The oil amount depends on the player's combined total oil stored in their lantern and as LampOil type items (the sum of the oil that the items would refill on use), determined when the player first looks at the OilBarrel. If the total oil is less than 100, the OilBarrel will contain exactly enough oil to bring it to 100. Otherwise (or if Hard Mode is enabled), it provides only 10 oil.

If the FullGameSave instance var is not enabled, OilBarrels can be used again when leaving a level and returning to it.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| FillSound || File (.snt) || || Sound played when lantern is filled. Incorrectly defined as a string in EntityTypes.cfg.
|-
| EmptySound || File (.snt) || || Sound played when barrel is empty. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

== EmotionStone ==

The memory capsule entities found in the game. Interacting with an EmotionStone causes an emotion flash effect to display, fading the screen to white and displaying a message.

{{HPL2 TypeVars Prop}}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| DescCat || String || || Category of text shown when in focus.
|-
| DescEntry || String || || Entry of text shown when in focus.
|-
| TextCat || String || || Category of text shown when interacted with. Typically "EmotionStone".
|-
| TextEntry || String || || Entry of text shown when interacted with.
|-
| Sound || File (.snt) || || Sound played when interacted with.
|-
|}

== NPC ==

Non-Player Characters are non-enemy characters. Agrippa and Alexander as they appear in-game are NPCs. Their only purpose is to stand in place and look at the player (if you enable the option).

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| MoveHeadBones || String || || List of bones that is rotated when the NPC rotates its head.
|-
| MoveHeadBoneMuls || String || || List of floats specifying how much each bone shall be rotated (-1 to 1).
|-
| HeadMoveSpeedMul || Float || 1 || Speed multiplier that that determines move speed based on distance to wanted angle.
|-
| HeadMoveMaxSpeed || Float || 1 || The max speed that the head moves in.
|-
| MaxHeadAngle || Float || 30 || The max angle that the head can turn when looking at the player.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| FollowPlayerArea || String || || When player is in this area, the NPC will look at him.
|-
| Awake || Bool || true || If the NPC is awake and looks at the player when in area.
|-
|}

== LevelDoor ==

A LevelDoor transports the player to the specified level when interacted with. The locked sounds, text, and destination can be entered in the Level Editor itself.

LevelDoors can also teleport the player (without a loading screen) if the same map is picked.

{{HPL2 TypeVars Prop}}

{|class=wikitable
|+Type Vars
! Name !! Type !! Default !! Description
|-
| EnterSound || File (.snt) || || Sound played when entering door. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ExitSound || File (.snt) || || Sound played when entering new map after having interacted with door. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Prop}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| TextEntry || String || || The text shown when door is in focus. Category is always Levels
|-
| StartPos || String || || The start position of the next map that the player is transported to.
|-
| MapFile || File (.map) || || The file of the next map.
|-
| Locked || Bool || false || If the door is locked.
|-
| LockedSound || File (.snt) || || Sound heard if locked and interacted with.
|-
| LockedTextCat || String || || Category of message shown if locked and interacted with.
|-
| LockedTextEntry || String || || Entry of message shown if locked and interacted with.
|-
| ShowStats || Bool || true || If stats of map it leads to should be shown (NOT IN USE) Non-functional. Formerly used to display a completion percentage.
|-
|}

== CritterBug ==

Critters like rats, roaches, or fish on the ground (or in the case of fish, water). They move around the room they are placed in and run away from the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MeshOffsetRot || Vector3 || 0 0 0 || The mesh offset rotation.
|-
| MeshOffsetPos || Vector3 || 0 0 0 || The mesh offset position.
|-
| MaxSpeedNormal || Float || 0.5 || Max speed when in normal state
|-
| MaxSpeedAfraid || Float || 1.3 || Max speed when in the scared state
|-
| Gravity || Float || 9.8 || Amount of gravity applied.
|-
| HasRandomPauses || Bool || false || If the critter shall have random pauses
|-
| RandomPauseTimeMinMax || Vector2 || 1 3 || Random time length of pause
|-
| RandomMoveTimeMinMax || Vector2 || 2 6 || Random time length of movement (between pauses)
|-
| PlayerFleeDistance || Float || 3 || The distance from player which it begins to flee
|-
| FleeMul || Float || 2.1 || Factor for moving away from player (if fleeing)
|-
| BackToSpawnPointMul || Float || 0.1 || Factor for moving back to spawn point
|-
| WanderCircleRadius || Float || 4 || Picture a circle in front critter at a certain distance. A point inside the circle is randomly selected and then the vector from the critter to this point is the speed added. The larger the circle, the more random the walk.
|-
| WanderCircleDist || Float || 2 || The distance at which the wander circle is placed. The higher the distance, the more likely the critter is to move forward.
|-
| NormalSound || File (.snt) || || Sound made when in normal state
|-
| NormalSoundRandMinMax || Vector2 || 1 3 || Random time length between normal sounds. x=min, y=max
|-
| ScaredSound || File (.snt) || || Sound made when in afraid state
|-
| ScaredSoundRandMinMax || Vector2 || 1 3 || Random time length between afraid sounds. x=min, y=max
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
|}

{{HPL2 InstanceVars Prop}}

== CritterSpider ==

A unused critter similar to the spider enemies from [[wikipedia:Penumbra: Overture|Penumbra: Overture]]. Capable of climbing walls and ceilings, as well as attacking the player.

{{HPL2 TypeVars Prop}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| MaxIdleSpeed || Float || 0.5 ||
|-
| MaxHuntSpeed || Float || 0.75 ||
|-
| HitSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| IdleSoundRandMinMax || Vector2 || 1 3 ||
|-
| AttackSound || File (.snt) || || Incorrectly defined as a string in EntityTypes.cfg.
|-
| AttackPlayerDistMinMax || Vector2 || 1 3 ||
|-
| HuntPlayerDist || Float || 8 ||
|-
| HuntTimeMinMax || Vector2 || 10 30 ||
|-
| MoveTimeMinMax || Vector2 || 4 8 ||
|-
| IdleTimeMinMax || Vector2 || 0.4 2 ||
|-
| DeathEntity || File (.ent) || || Entity created when dead.
|-
| DeathPS || File (.ps) || || Particle created when dead.
|-
| DeathSound || File (.snt) || || Sound played when dead.
|-
| AttackSizeRadius || Float || 0.3 ||
|-
| AttackOffset || Vector3 || 0 0 1 ||
|-
| AttackDamageMinMax || Vector2 || 5 15 ||
|-
| AttackForce || Vector2 || 5 1 ||
|-
| AttackStrength || Int || 1 ||
|-
| AttackHitSound || File (.snt) || ||
|-
|}

{{HPL2 InstanceVars Prop}}

== Enemy_Grunt ==

An Enemy_Grunt entity is a standard enemy entity, used for the Grunt, Brute, and Suitor. Enemy entities require advanced setup, and should include animations added through Settings > Animations. Enemy properties can be modified in the entity type window, like certain sounds and music tracks playing, the enemy's awareness levels and damage, speed and other similar settings. An enemy does not use a collision box, but instead a skeleton and the aforementioned properties to determine how to collide/hit something.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 15 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 10 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 3.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 2.0 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 4.5 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.5 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 5 || The distance where the move toward enemy check starts
|-
| IdleExtraTimeMin || Float || 2 || Min time between extra idle animations
|-
| IdleExtraTimeMax || Float || 6 || Max time between extra idle animations
|-
| IdleExtraNum || Int || 3 || Number of extra idle animations
|-
|}

{{HPL2 InstanceVars Enemy}}

== Enemy_ManPig ==
{{clr}}
{{ReqVer|1.3}}

An enemy type ported from A Machine For Pigs. Compare to the [[HPL2/AMFP/NewEntities#Enemy_ManPig|AMFP version]] of the enemy.

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| Quadruped_Walk_ForwardSpeed || Float || 1.0 || Forward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_BackwardSpeed || Float || 1.0 || Backward speed when walking on all fours, in meters per second.
|-
| Quadruped_Walk_ForwardAcc || Float || 2.0 ||
|-
| Quadruped_Walk_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_Run_ForwardSpeed || Float || 3.0 || Forward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_BackwardSpeed || Float || 2.0 || Backward speed when running on all fours, in meters per second.
|-
| Quadruped_Run_ForwardAcc || Float || 4.0 ||
|-
| Quadruped_Run_ForwardDeacc || Float || 8.0 ||
|-
| Quadruped_StoppedToWalkSpeed || Float || 0.05 || Speed at which the walk animation is played when on all fours
|-
| Quadruped_WalkToStoppedSpeed || Float || 0.02 || Speed at which walk goes to stopped when on all fours
|-
| Quadruped_WalkToRunSpeed || Float || 2.0 || Speed at which walk turns to run animation when on all fours
|-
| Quadruped_RunToWalkSpeed || Float || 0.9 || Speed at which run turns to walk when on all fours
|-
| NoticeSound || File (.snt) || || Sound played when enemy notices that player is nearby
|-
| GiveUpNoticeSound || File (.snt) || || Sound played when enemy gives up investigation (after a notice)
|-
| EnabledSound || File (.snt) || || Sound played when enemy is enabled
|-
| GroggyDamageCount || Float || 1 || The accumulated amount of damage the enemy can take before getting groggy by the hit. The enemy will flinch after taking this amount of damage.
|-
| AlertToHuntDistance || Float || 6 || If range is above this then enemy can go from alert to hunt
|-
| AlertToInstantHuntDistance || Float || 2.5 || If range is below this, enemy geos instantly to hunt.
|-
| HuntPauseMinTime || Float || 0.5 || Min time enemy spends not attacking after an attack.
|-
| HuntPauseMaxTime || Float || 1.0 || Max time enemy spends not attacking after an attack.
|-
| IncreaseAlertSpeedDistance || Float || 6 || Distance at which the alert move speed increases.
|-
| IncreasedAlertSpeedMul || Float || 1.25 || The amount that move speed is multiplied by when alert.
|-
| AlertRunTowardsToHuntLimit || Float || 30 || The accumulated limit value when alert goes to hunt because of player running towards enemy.
|-
| AlertRunTowardsCheckDistance || Float || 6 || The distance where the move toward enemy check starts
|-
| IsTelsa || Bool || false || If this is the tesla pig
|-
| TeslaSoundLoop || File (.snt) || || Sound file played when the tesla's proximity effects are active. Incorrectly defined as a string in EntityTypes.cfg.
|-
| ChaseSound || File (.snt) || || Played when the pig is chasing. Incorrectly defined as a string in EntityTypes.cfg.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Instance Vars
! Name !! Type !! Default !! Description
|-
| Pose || String || Biped || The pose of the enemy to start with Can be "Biped" or "Quadruped".
|-
| ThreatenOnAlert || Bool || false || If the pig should stand still and threaten instead of walking towards player when in alert mode.
|-
| FleeFromPlayer || Bool || false || The pig will flee instead of hunting (threaten if ThreatenOnAlert). Disabled if far enough away. Will attack if cornered.
|-
| AutoDisableAfterFlee || Bool || false || If pig should be disabled after having fled (if possible)
|-
| LanternSensitivity || Float || 1 || A modifier for how quickly the pig reacts to being shined on by the lantern. Not defined in EntityTypes.cfg.
|-
| IdleBehavior || String || None || The behavior used when there are no patrol nodes left to walk. Can be "None", "Stalk", or "Track".
|-
| PlayActivateSound || Bool || true || If the enemy can play its EnabledSound.
|-
| AllowZeroNodeWaitTimes || Bool || false || If set to true, path node wait times with value 0 actually mean no waiting Normally, specifying a wait time of 0 in <code>AddEnemyPatrolNode</code> results in a wait time of 1-3 seconds.
|-
| PatrolMoveSpeed || String || Walk || Whether this pig walks or runs along its patrol Can be "Walk" or "Run".
|-
| DamageMul || Float || 1 || Multiplier for the enemy's attack damage. Not defined in EntityTypes.cfg.
|-
| RunSpeedMul || Float || 1 || Multiplier for the enemy's run speed. Not defined in EntityTypes.cfg.
|-
| HuntPauseTimeMul || Float || 1 || Multiplier for wait time between attacks.
|-
|}

== Enemy_Waterlurker ==

Enemy type of the "water monster". Since you can't assign animations to it, you might as well just use the normal waterlurker of the base game unless you want to change its properties (such as damage, movement speed, or music played).

{{HPL2 TypeVars Enemy}}

{|class="wikitable mw-collapsible mw-collapsed"
|+style="white-space:nowrap;text-align:-webkit-center"| Type Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0.6 || The y-distance from the enemy that the player is detected.
|-
| EatDamage || Float || 20 || The damage dealt to food being eaten
|-
| AfterAttackPauseTime || Float || 0 || The amount of timer lurker waits after an attack
|-
| SplashPS_Walk || File (.ps) || || Particle system created at surface when walking.
|-
| SplashPS_Run || File (.ps) || || Particle system created at surface when running.
|-
| SplashPS_Eat || File (.ps) || || Particle system created at surface when eating.
|-
| SplashPS_Attack || File (.ps) || || Particle system created at surface when attacking.
|-
| SplashSound_Walk || File (.snt) || || Sound played when walking.
|-
| SplashSound_Run || File (.snt) || || Sound played when running.
|-
| SplashSound_Eat || File (.snt) || || Sound played when eating.
|-
| SplashSound_Attack || File (.snt) || || Sound played when attacking.
|-
|}

{{HPL2 InstanceVars Enemy}}

{|class=wikitable
|+Instance Vars
! Name !! Type !! Default !! Description
|-
| PlayerDetectionHeight || Float || 0 || If equal or below 0 the default in data file is used! The y-distance from the enemy that the player is detected.
|-
|}

== PlayerHands ==

Player's hands. Unless you want to make a different looking hand for a full conversion mod, you don't have to worry about this.

== HandObject ==

The only available HandObject is the lantern. It is used in conjunction with a <code>.ho</code> config file to place it properly in PlayerHands.

Mostly a remnant of cut items that functioned as weapons, like in [[wikipedia:Penumbra: Overture|Penumbra: Overture]], including the pickaxe from that game.

HPL2/Engine Scripts

2025-03-15T20:19:13Z

BoxFigs: /* Player */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.
{{bug|Sanity drain is reenabled on loading a save, as the game is unable to load the value properly from the save data.}}

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<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 &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<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 &in 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 &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in 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 &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/Engine Scripts

2025-03-02T05:05:25Z

BoxFigs: /* Enemies */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<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 &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<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 &in 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 &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in 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 &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 entity 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/TDD/Change Custom Story into Full Conversion Mod

2025-01-25T17:20:34Z

BoxFigs:

{{constructionNotice|This page is still being written and is currently incomplete}}

Since version 1.5 of Amnesia The Dark Descent (release in July 2023), a new field has been added to the custom_story_settings.cfg file. This field allows you to specify a main_init.cfg file, which is the main file that [[HPL2/TDD/Full Conversion Mod|full conversion mods]] use to launch. This means you can now create full conversion mods from a custom story, and they will still show up in the main game menu. This unlocks all the power of full conversion mods, while maintaining most of the simplicity of a custom story.

==Setup==
If you have a custom story that you want to transform into a full conversion mod, start by adding the new field to your custom_story_settings.cfg:
<syntaxhighlight lang="xml">
<Main
Name = "My story"
Author = "Me"

...

InitCfgFile = "config/main_init.cfg"
/>
</syntaxhighlight>
Specifying this field will disable <code>MapsFolder</code>, <code>StartMap</code> and <code>StartPos</code>, as these fields will instead be read from the main_init.cfg file. It will also disable <code>ExtraLangFilePrefix</code> and <code>DefaultExtraLangFile</code>, as the game will instead use the primary lang files specified in main_init.cfg. The description of your custom story will instead be located in said lang file, in the <code>CustomStoryMain</code> category.

From this point on, you can follow tutorials for full conversion mods. Your mod folder will remain <code>custom_stories/<your story></code>. For example, if your story folder is named "Ascent", your main init file should exist at <code>custom_stories/Ascent/config/main_init.cfg</code> (reflecting what you put in the <code>InitCfgFile</code> above). Create the "config" folder and the "main_init.cfg" file. The contents of your main_init.cfg file can start as such (Remember to change the references to "Ascent" to reflect your own mod, such as MainSaveFolder and GameName):

<syntaxhighlight lang="xml">
<ConfigFiles
Resources = "resources.cfg"
Materials = "materials.cfg"

Game = "config/game.cfg"
Menu = "config/menu.cfg"
PreMenu = "config/pre_menu.cfg"
Demo = "config/demo.cfg"

DefaultMainSettings = "config/default_main_settings.cfg"
DefaultMainSettingsSDL2 = "config/default_main_settings_sdl2.cfg"

DefaultMainSettingsLow = "launcher/default_main_settings_low.cfg"
DefaultMainSettingsMedium = "launcher/default_main_settings_medium.cfg"
DefaultMainSettingsHigh = "launcher/default_main_settings_high.cfg"

DefaultUserSettings = "config/default_user_settings.cfg"
DefaultUserKeys = "config/default_user_keys.cfg"
DefaultUserKeysSDL2 = "config/default_user_keys_sdl2.cfg"

DefaultBaseLanguage = "base_english.lang"
DefaultGameLanguage = "english.lang"
/>

<Directories
MainSaveFolder = "Ascent"

BaseLanguageFolder = "config/"
GameLanguageFolder = "config/lang_main/"

CustomStoryPath = "custom_stories"
/>

<Variables
GameName = "Ascent, an Amnesia mod"
/>

<StartMap
File = "level_01.map"
Folder = "maps/"
Pos = "PlayerStartArea_1"
/>
</syntaxhighlight>

Paths specified in this file are relative paths starting from the custom story's main folder, eg: "custom_stories/Ascent". For example, leaving Resources as "resources.cfg" means it should exist at "custom_stories/Ascent/resources.cfg". If a file is not found here, it will fall back to using the file specified in the base game main_init.cfg.

{{note|resources.cfg is required for your full conversion to load '''any''' files contained in your custom story's folder, including maps!}}
Simply copying the original resources.cfg and placing it in your custom story's folder is sufficient. Unlike the base game, full conversions will not automatically read from the "lang" folder, so you will have to add it to resources.cfg. Your custom story can now override base game assets with its own.

==Additional notes==

When it comes to file loading, lang files are a special case; they operate on a per-entry basis, meaning any entries not found in your custom story's lang file will load from the base game's lang file instead. This means you can override any existing lang entry as well as add your own, but you can also use any entry from the base game without needing to add it to your file.

Because of the way total conversions work, custom stories cannot load the Justine config and lang files (referred to as "ptest" internally). For example, attempting to specify "ptest_materials.cfg" in your main_init.cfg will not work. Instead, you will have to copy the file to your custom story's folder, which you can rename to materials.cfg because full conversions can load only one config. Similarly, a full conversion won't be able to load any files from <code>config/lang_ptest</code>, so you will need to copy over any entries to your own lang file. However, Justine assets can be loaded without issue, as they exist in subfolders that are loaded by the base resources.cfg.

HPL2/TDD/Change Custom Story into Full Conversion Mod

2025-01-25T17:19:58Z

BoxFigs:

{{constructionNotice|This page is still being written and is currently incomplete}}

Since version 1.5 of Amnesia The Dark Descent (release in July 2023), a new field has been added to the custom_story_settings.cfg file. This field allows you to specify a main_init.cfg file, which is the main file that full conversion mods use to launch. This means you can now create [[HPL2/TDD/Full Conversion Mod|full conversion mods]] from a custom story, and they will still show up in the main game menu. This unlocks all the power of full conversion mods, while maintaining most of the simplicity of a custom story.

==Setup==
If you have a custom story that you want to transform into a full conversion mod, start by adding the new field to your custom_story_settings.cfg:
<syntaxhighlight lang="xml">
<Main
Name = "My story"
Author = "Me"

...

InitCfgFile = "config/main_init.cfg"
/>
</syntaxhighlight>
Specifying this field will disable <code>MapsFolder</code>, <code>StartMap</code> and <code>StartPos</code>, as these fields will instead be read from the main_init.cfg file. It will also disable <code>ExtraLangFilePrefix</code> and <code>DefaultExtraLangFile</code>, as the game will instead use the primary lang files specified in main_init.cfg. The description of your custom story will instead be located in said lang file, in the <code>CustomStoryMain</code> category.

From this point on, you can follow tutorials for full conversion mods. Your mod folder will remain <code>custom_stories/<your story></code>. For example, if your story folder is named "Ascent", your main init file should exist at <code>custom_stories/Ascent/config/main_init.cfg</code> (reflecting what you put in the <code>InitCfgFile</code> above). Create the "config" folder and the "main_init.cfg" file. The contents of your main_init.cfg file can start as such (Remember to change the references to "Ascent" to reflect your own mod, such as MainSaveFolder and GameName):

<syntaxhighlight lang="xml">
<ConfigFiles
Resources = "resources.cfg"
Materials = "materials.cfg"

Game = "config/game.cfg"
Menu = "config/menu.cfg"
PreMenu = "config/pre_menu.cfg"
Demo = "config/demo.cfg"

DefaultMainSettings = "config/default_main_settings.cfg"
DefaultMainSettingsSDL2 = "config/default_main_settings_sdl2.cfg"

DefaultMainSettingsLow = "launcher/default_main_settings_low.cfg"
DefaultMainSettingsMedium = "launcher/default_main_settings_medium.cfg"
DefaultMainSettingsHigh = "launcher/default_main_settings_high.cfg"

DefaultUserSettings = "config/default_user_settings.cfg"
DefaultUserKeys = "config/default_user_keys.cfg"
DefaultUserKeysSDL2 = "config/default_user_keys_sdl2.cfg"

DefaultBaseLanguage = "base_english.lang"
DefaultGameLanguage = "english.lang"
/>

<Directories
MainSaveFolder = "Ascent"

BaseLanguageFolder = "config/"
GameLanguageFolder = "config/lang_main/"

CustomStoryPath = "custom_stories"
/>

<Variables
GameName = "Ascent, an Amnesia mod"
/>

<StartMap
File = "level_01.map"
Folder = "maps/"
Pos = "PlayerStartArea_1"
/>
</syntaxhighlight>

Paths specified in this file are relative paths starting from the custom story's main folder, eg: "custom_stories/Ascent". For example, leaving Resources as "resources.cfg" means it should exist at "custom_stories/Ascent/resources.cfg". If a file is not found here, it will fall back to using the file specified in the base game main_init.cfg.

{{note|resources.cfg is required for your full conversion to load '''any''' files contained in your custom story's folder, including maps!}}
Simply copying the original resources.cfg and placing it in your custom story's folder is sufficient. Unlike the base game, full conversions will not automatically read from the "lang" folder, so you will have to add it to resources.cfg. Your custom story can now override base game assets with its own.

==Additional notes==

When it comes to file loading, lang files are a special case; they operate on a per-entry basis, meaning any entries not found in your custom story's lang file will load from the base game's lang file instead. This means you can override any existing lang entry as well as add your own, but you can also use any entry from the base game without needing to add it to your file.

Because of the way total conversions work, custom stories cannot load the Justine config and lang files (referred to as "ptest" internally). For example, attempting to specify "ptest_materials.cfg" in your main_init.cfg will not work. Instead, you will have to copy the file to your custom story's folder, which you can rename to materials.cfg because full conversions can load only one config. Similarly, a full conversion won't be able to load any files from <code>config/lang_ptest</code>, so you will need to copy over any entries to your own lang file. However, Justine assets can be loaded without issue, as they exist in subfolders that are loaded by the base resources.cfg.

HPL2/TDD/Change Custom Story into Full Conversion Mod

2025-01-25T17:15:48Z

BoxFigs:

{{constructionNotice|This page is still being written and is currently incomplete}}

Since version 1.5 of Amnesia The Dark Descent (release in July 2023), a new field has been added to the custom_story_settings.cfg file. This field allows you to specify a main_init.cfg file, which is the main file that full conversion mods use to launch. This means you can now create full conversion mods from a custom story, and they will still show up in the main game menu. This unlocks all the power of full conversion mods, while maintaining most of the simplicity of a custom story.

==Setup==
If you have a custom story that you want to transform into a full conversion mod, start by adding the new field to your custom_story_settings.cfg:
<syntaxhighlight lang="xml">
<Main
Name = "My story"
Author = "Me"

...

InitCfgFile = "config/main_init.cfg"
/>
</syntaxhighlight>
Specifying this field will disable <code>MapsFolder</code>, <code>StartMap</code> and <code>StartPos</code>, as these fields will instead be read from the main_init.cfg file. It will also disable <code>ExtraLangFilePrefix</code> and <code>DefaultExtraLangFile</code>, as the game will instead use the primary lang files specified in main_init.cfg. The description of your custom story will instead be located in said lang file, in the <code>CustomStoryMain</code> category.

From this point on, you can follow tutorials for full conversion mods. Your mod folder will remain <code>custom_stories/<your story></code>. For example, if your story folder is named "Ascent", your main init file should exist at <code>custom_stories/Ascent/config/main_init.cfg</code> (reflecting what you put in the <code>InitCfgFile</code> above). Create the "config" folder and the "main_init.cfg" file. The contents of your main_init.cfg file can start as such (Remember to change the references to "Ascent" to reflect your own mod, such as MainSaveFolder and GameName):

<syntaxhighlight lang="xml">
<ConfigFiles
Resources = "resources.cfg"
Materials = "materials.cfg"

Game = "config/game.cfg"
Menu = "config/menu.cfg"
PreMenu = "config/pre_menu.cfg"
Demo = "config/demo.cfg"

DefaultMainSettings = "config/default_main_settings.cfg"
DefaultMainSettingsSDL2 = "config/default_main_settings_sdl2.cfg"

DefaultMainSettingsLow = "launcher/default_main_settings_low.cfg"
DefaultMainSettingsMedium = "launcher/default_main_settings_medium.cfg"
DefaultMainSettingsHigh = "launcher/default_main_settings_high.cfg"

DefaultUserSettings = "config/default_user_settings.cfg"
DefaultUserKeys = "config/default_user_keys.cfg"
DefaultUserKeysSDL2 = "config/default_user_keys_sdl2.cfg"

DefaultBaseLanguage = "base_english.lang"
DefaultGameLanguage = "english.lang"
/>

<Directories
MainSaveFolder = "Ascent"

BaseLanguageFolder = "config/"
GameLanguageFolder = "config/lang_main/"

CustomStoryPath = "custom_stories"
/>

<Variables
GameName = "Ascent, an Amnesia mod"
/>

<StartMap
File = "level_01.map"
Folder = "maps/"
Pos = "PlayerStartArea_1"
/>
</syntaxhighlight>

Paths specified in this file are relative paths starting from the custom story's main folder, eg: "custom_stories/Ascent". For example, leaving Resources as "resources.cfg" means it should exist at "custom_stories/Ascent/resources.cfg". If a file is not found here, it will fall back to using the file specified in the base game main_init.cfg.

{{note|resources.cfg is required for your full conversion to load '''any''' files contained in your custom story's folder, including maps!}}
Simply copying the original resources.cfg and placing it in your custom story's folder is sufficient. Unlike the base game, full conversions will not automatically read from the "lang" folder, so you will have to add it to resources.cfg. Your custom story can now override base game assets with its own.

==Additional notes==

When it comes to file loading, lang files are a special case; they operate on a per-entry basis, meaning any entries not found in your custom story's lang file will load from the base game's lang file instead. This means you can override any existing lang entry as well as add your own, but you can also use any entry from the base game without needing to add it to your file.

Because of the way total conversions work, custom stories cannot load the Justine config and lang files (referred to as "ptest" internally). For example, attempting to specify "ptest_materials.cfg" in your main_init.cfg will not work. Instead, you will have to copy the file to your custom story's folder, which you can rename to materials.cfg because full conversions can load only one config. Similarly, a full conversion won't be able to load any files from <code>config/lang_ptest</code>, so you will need to copy over any entries to your own lang file. However, Justine assets can be loaded without issue, as they exist in subfolders that are loaded by the base resources.cfg.

HPL2/Engine Scripts

2025-01-19T23:54:43Z

BoxFigs: /* Sounds & Music */

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the voice and sound are played from
#''afMinDistance ''- minimum distance the voice and sound are heard
#''afMaxDistance ''- maximum distance the voice and sound are heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<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 &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<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 &in 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 &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in 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 &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/TDD/Change Custom Story into Full Conversion Mod

2025-01-19T22:47:34Z

BoxFigs:

{{constructionNotice|This page is still being written and is currently incomplete}}

Since version 1.5 of Amnesia The Dark Descent (release in July 2023), a new field has been added to the custom_story_settings.cfg file. This field allows you to specify a main_init.cfg file, which is the main file that full conversion mods use to launch. This means you can now create full conversion mods from a custom story, and they will still show up in the main game menu. This unlocks all the power of full conversion mods, while maintaining most of the simplicity of a custom story.

If you have a custom story that you want to transform into a full conversion mod, start by adding the new field to your custom_story_settings.cfg:
<syntaxhighlight lang="xml">
<Main
Name = "My story"
Author = "Me"

...

InitCfgFile = "config/main_init.cfg"
/>
</syntaxhighlight>
Specifying this field will disable <code>MapsFolder</code>, <code>StartMap</code> and <code>StartPos</code>, as these fields will instead be read from the main_init.cfg file. It will also disable <code>ExtraLangFilePrefix</code> and <code>DefaultExtraLangFile</code>, as the game will instead use the primary lang files specified in main_init.cfg. The description of your custom story will instead be located in said lang file, in the <code>CustomStoryMain</code> category.

From this point on, you can follow tutorials for full conversion mods. Your mod folder will remain <code>custom_stories/<your story></code>. For example, if your story folder is named "Ascent", your main init file should exist at <code>custom_stories/Ascent/config/main_init.cfg</code> (reflecting what you put in the <code>InitCfgFile</code> above). Create the "config" folder and the "main_init.cfg" file. The contents of your main_init.cfg file can start as such (Remember to change the references to "Ascent" to reflect your own mod, such as MainSaveFolder and GameName):
<syntaxhighlight lang="xml">
<ConfigFiles
Resources = "resources.cfg"
Materials = "materials.cfg"

Game = "config/game.cfg"
Menu = "config/menu.cfg"
PreMenu = "config/pre_menu.cfg"
Demo = "config/demo.cfg"

DefaultMainSettings = "config/default_main_settings.cfg"
DefaultMainSettingsSDL2 = "config/default_main_settings_sdl2.cfg"

DefaultMainSettingsLow = "launcher/default_main_settings_low.cfg"
DefaultMainSettingsMedium = "launcher/default_main_settings_medium.cfg"
DefaultMainSettingsHigh = "launcher/default_main_settings_high.cfg"

DefaultUserSettings = "config/default_user_settings.cfg"
DefaultUserKeys = "config/default_user_keys.cfg"
DefaultUserKeysSDL2 = "config/default_user_keys_sdl2.cfg"

DefaultBaseLanguage = "base_english.lang"
DefaultGameLanguage = "english.lang"
/>

<Directories
MainSaveFolder = "Ascent"

BaseLanguageFolder = "config/"
GameLanguageFolder = "config/lang_main/"

CustomStoryPath = "custom_stories"
/>

<Variables
GameName = "Ascent, an Amnesia mod"
/>

<StartMap
File = "level_01.map"
Folder = "maps/"
Pos = "PlayerStartArea_1"
/>
</syntaxhighlight>

Note: Paths specified in this file are relative paths starting from the custom story's main folder, eg: "custom_stories/Ascent". For example, leaving Resources as "resources.cfg" means it should exist at "custom_stories/Ascent/resources.cfg". If a file is not found here, it will fall back to using the file specified in the base game main_init.cfg.

'''resources.cfg is required for your full conversion to load any files contained in your custom story's folder!''' Simply copying the original resources.cfg and placing it in your custom story's folder is sufficient. Note that unlike the base game, full conversions will not automatically read from the "lang" folder, so you will have to add it to resources.cfg. Your custom story can now override base game assets with its own.

Lang files are a special case: they operate on a per-entry basis, meaning any entries not found in your custom story's lang file will load from the base game's lang file instead. This means you can override any existing lang entry as well as add your own, but you can also use any entry from the base game without needing to add it to your file.

HPL2/TDD/Change Custom Story into Full Conversion Mod

2025-01-19T22:16:37Z

BoxFigs:

{{constructionNotice|This page is still being written and is currently incomplete}}

Since version 1.5 of Amnesia The Dark Descent (release in July 2023), a new field has been added to the custom_story_settings.cfg file. This field allows you to specify a main_init.cfg file, which is the main file that full conversion mods use to launch. This means you can now create full conversion mods from a custom story, and they will still show up in the main game menu. This unlocks all the power of full conversion mods, while maintaining most of the simplicity of a custom story.

If you have a custom story that you want to transform into a full conversion mod, start by adding the new field to your custom_story_settings.cfg:
<syntaxhighlight lang="xml">
<Main
Name = "My story"
Author = "Me"

...

InitCfgFile = "config/main_init.cfg"
/>
</syntaxhighlight>
Specifying this field will disable <code>MapsFolder</code>, <code>StartMap</code> and <code>StartPos</code>, as these fields will instead be read from the main_init.cfg file. It will also disable <code>ExtraLangFilePrefix</code> and <code>DefaultExtraLangFile</code>, as the game will instead use the primary lang files specified in main_init.cfg. The description of your custom story will instead be located in said lang file, in the <code>CustomStoryMain</code> category.

From this point on, you can follow tutorials for full conversion mods. Your mod folder will remain <code>custom_stories/<your story></code>. For example, if your story folder is named "Ascent", your main init file should exist at <code>custom_stories/Ascent/config/main_init.cfg</code> (reflecting what you put in the <code>InitCfgFile</code> above). Create the "config" folder and the "main_init.cfg" file. The contents of your main_init.cfg file can start as such (Remember to change the references to "Ascent" to reflect your own mod, such as MainSaveFolder and GameName):
<syntaxhighlight lang="xml">
<ConfigFiles
Resources = "resources.cfg"
Materials = "materials.cfg"

Game = "config/game.cfg"
Menu = "config/menu.cfg"
PreMenu = "config/pre_menu.cfg"
Demo = "config/demo.cfg"

DefaultMainSettings = "config/default_main_settings.cfg"
DefaultMainSettingsSDL2 = "config/default_main_settings_sdl2.cfg"

DefaultMainSettingsLow = "launcher/default_main_settings_low.cfg"
DefaultMainSettingsMedium = "launcher/default_main_settings_medium.cfg"
DefaultMainSettingsHigh = "launcher/default_main_settings_high.cfg"

DefaultUserSettings = "config/default_user_settings.cfg"
DefaultUserKeys = "config/default_user_keys.cfg"
DefaultUserKeysSDL2 = "config/default_user_keys_sdl2.cfg"

DefaultBaseLanguage = "base_english.lang"
DefaultGameLanguage = "english.lang"
/>

<Directories
MainSaveFolder = "Ascent"

BaseLanguageFolder = "config/"
GameLanguageFolder = "config/lang_main/"

CustomStoryPath = "custom_stories"
/>

<Variables
GameName = "Ascent, an Amnesia mod"
/>

<StartMap
File = "level_01.map"
Folder = "maps/"
Pos = "PlayerStartArea_1"
/>
</syntaxhighlight>

Note: Paths specified in this file are relative paths starting from the custom story's main folder, eg: "custom_stories/Ascent". For example, leaving Resources as "resources.cfg" means it should exist at "custom_stories/Ascent/resources.cfg". If a file is not found here, it will fall back to using the file specified in the base game main_init.cfg.

'''resources.cfg is required for your full conversion to load any files contained in your custom story's folder!''' Simply copying the original resources.cfg and placing it in your custom story's folder is sufficient. Note that unlike the base game, full conversions will not automatically read from the "lang" folder, so you will have to add it to resources.cfg. Your custom story can now override base game assets with its own.

Lang files are a special case: they operate on a per-entry basis, meaning any entries not found in your custom story's lang file will load from the base game's lang file instead. This means you can override any existing lang entry as well as add your own, but you can also use any entry from the base game without needing to add them to yours.

HPL2/ScriptReference/Constants And Enumerations

2025-01-19T21:40:58Z

BoxFigs:

== At a Glance ==

Constants and enumerations allow you to define names which refer to values that should never change during the execution of a script.

'''Constants'''
<syntaxhighlight lang="c++">// Some math constants:
const float PI = 3.1415926f;
const float E = 2.7182818f;

// Integer constants:
// The constants in this example define when should collision events take place;
// intended to be used with the AddEntityCollideCallback() engine function

const int COLLIDE_ON_ENTER = 1;
const int COLLIDE_ON_LEAVE = -1;
const int COLLIDE_ON_BOTH = 0;

// Usage:
AddEntityCollideCallback("Player", "Area_Example", "ExampleCallback", false, COLLIDE_ON_BOTH);
</syntaxhighlight>

'''Enumerated Constants (Enumerations)'''
<syntaxhighlight lang="c++">enum Color // Note: Enums are based on the int type.
{
Red, // has the default value of: 0
Green, // value: (previous + 1) = 1
Blue // value: (previous + 1) = 2, etc, if more added...
}

// Usage:
Color col = Color::Blue; // emphasizes the containing enum, improves code clarity

// Or just:
Color col = Blue; // same effect

// Assigning an integer value is not possible without an explicit conversion:
Color col = 2; // Causes compilation error!

// Converting from integers - should generally be avoided:
Color col = Color(2); // Assigns Blue to col, since 2 corresponds to Color::Blue

// However:
Color col = Color(-15); // Has a value of -15, which is not tied to any Color! Could be a problem!

// This is allowed:
int colValue = col; // so, enums can be passed to functions expecting ints --> see example below

// Enumerations - choosing your own values
enum CollisionState
{
Leave = -1, // = -1
Both, // = 0 (previous + 1)
Enter // = 1 (previous + 1)
}

// Used as parameters to a function:
AddEntityCollideCallback("Player", "Area_Example", "ExampleCallback", false, CollisionState::Both);

// You can define all or some of the values; those left undefined will be
// assigned the value of previous_constant + 1
enum Ending
{
Good = 1, // = 1
ReallyGood, // = 2 (previous + 1)
Neutral = -10, // = -10
ReallyBad = -2, // = -2
Bad, // = -1 (previous + 1)
Default = Neutral // = -10 <-- You can use previously defined constants
}

// Binary FLAGS:
enum QuestState
{
FoundNote1 = 0x01, // HEX for 1, which is in binary: 0000 0001
FoundNote2 = 0x02, // HEX for 2, which is in binary: 0000 0010
FoundItem = 0x04, // HEX for 4, which is in binary: 0000 0100
FoundPassage = 0x08, // HEX for 8, which is in binary: 0000 1000
FoundAll = 0x0F // HEX for 15, which is in binary: 0000 1111
}
</syntaxhighlight>

== Discussion ==

Often, you'll need to define some values which are supposed to remain unchanged (constant) throughout the script, for the entire duration of its execution. You could use variables for this, being very careful not to change them, but even the best of scripters can make a mistake. The script language provides several constructs which enable you to define such constants, so that you can let the compiler worry about keeping them safe from you accidentally changing them. If you by any chance make a mistake and try to reassign a constant, the compiler will greet you with an error message - which is a good thing, because this protects your script from some potentially sneaky bugs.

Constants can be of any type, and are declared almost exactly the same way as variables; the only difference is that the declaration is preceded by the ''const'' keyword, and that the value has to be assigned immediately (because it cannot be changed later on). '''const''' ''typeName'' ''constantName'' = ''value'';

The names of the constants defined are often written using ALL_CAPS, and individual words are separated with an underscore ''_''. This naming convention enables you to easily distinguish such constants from variables and other names, ''but'' it is a matter of preference, and is not required by the language.

It is common to define consts for mathematical and scientific constants, such are the numbers ''pi'', ''e'', or the gravitational acceleration ''g'', etc. Other uses of constants include defining minimum or maximum values for something (max items, max health, etc...), or passing them as special values to functions (more on that later on).

<syntaxhighlight lang="c++">
const float PI = 3.1415926f;
const float E = 2.7182818f;

const int MIN_ITEMS_FOUND = 2;
const int MAX_ITEMS_FOUND = 5;

const float MAX_HEALTH = 100.0f;

const float MAX_WAIT_TIME = 10.0f; // in seconds
</syntaxhighlight>

You can use constants in various ways, for example, in conditions of [[HPL2/ScriptReference/Control flow - Conditional Statements|conditional statements]] and [[HPL2/ScriptReference/Control flow - Loops|loops]], or in mathematical expressions, or you can assign them to variables (note: when assigning to a variable, the variable gets a copy of the value stored in the constant; the variable can then be manipulated without affecting the constant itself). For example:
<syntaxhighlight lang="c++">
float radius = 2.5f;
float circleArea = PI * radius * radius;

// OR
float health = MAX_HEALTH;

// later on...
health = 0.0f;
</syntaxhighlight>

=== Constants As Function Parameters ===

A function can take a parameter to decide which way should it go about doing its job (see [[HPL2/ScriptReference/Functions Part 1|Functions - Part 1]] to learn more about functions). If there are only two ways, the function might accept a ''bool'' parameter, and make a decision based on whether the value of that parameter is ''true'' or ''false''.
For example, the engine exposes this predefined function: ''SetFogActive(bool abActive)''. It takes a single ''bool'' parameter, which it uses to decide if the fog should be activated or deactivated.

Often, though, there's more than two options, and in that case integers can be used to represent each of them. This approach is versatile in that it can be used to represent a varying number of options, however, the drawback is that the user of the function needs to remember the meanings of these numbers (sometimes referred to as "magic numbers"), and their meanings cannot be inferred just by reading the code. Amnesia provides some functions which use special-meaning integer values as parameters. Such parameters often appear in callbacks as well.
For example, this predefined function, which forces a lever to be stuck in a certain position, takes three parameters:

<syntaxhighlight lang="c++">void SetLeverStuckState(string& leverName, int stuckState, bool useEffects);</syntaxhighlight>

The first parameter ''leverName'' tells it to which lever it should be applied to. The third parameter ''useEffects'' we can ignore in this discussion. The second parameter, ''stuckState'' is an ''int'' parameter, and it tells the function in which position the lever should be stuck. It can be either:
* ''-1'' - stuck at "min" side
* ''1'' - stuck at "max" side
* ''0'' - not stuck, rests in the middle

This is how the function is used: if you wanted a lever which, say, controls the supply of electricity, called "Lever_Power", to be stuck at the "max" position, which will mean that the power is on, you would write:
<syntaxhighlight lang="c++">SetLeverStuckState("Lever_Power", 1, false);</syntaxhighlight>

As you can see, you can't tell, if you don't already know, what ''1'' means just by looking at that line of code - you have to consult the documentation. The number itself is essentially meaningless to a human reader. ''Constants can help with this:''
<syntaxhighlight lang="c++">
// Globally declared constants (script-scope):
const int LEVER_MIN = -1;
const int LEVER_MAX = 1;
const int LEVER_FREE = 0;

//...

// Elsewhere in the program:
SetLeverStuckState("Lever_Power", LEVER_MAX, false);
</syntaxhighlight>

Now it's clear that the the function makes the lever stuck in the "max" state. But, constants can do even better than that. It is still not obvious what this "max" state means in the context of the game (that is, your custom story or full conversion) itself. We assumed earlier that the lever is used to turn the power on or off. Thus, to convey this information, the code can be modified like this:
<syntaxhighlight lang="c++">
// Globally declared constants (script-scope):

// Leave these for any other, generic levers, which might
// possibly exist on the map
const int LEVER_MIN = -1;
const int LEVER_MAX = 1;
const int LEVER_FREE = 0;

// Specific constants for the power-on/off lever:
const int LEVER_POWER_OFF = LEVER_MIN;
const int LEVER_POWER_ON = LEVER_MAX;

//...

// Elsewhere in the program:
SetLeverStuckState("Lever_Power", LEVER_POWER_ON, false);
</syntaxhighlight>

Now it is fairly obvious what the call to SetLeverStuckState() function does.

=== Enumerations ===

Often you need to define a set of constants that are somehow related to each other, especially when they are intended to be passed as function parameters, like in the examples above. ''Enumerations'' provide a convenient language mechanism which enables you to group related constants together under one name. The syntax is as follows (in pseudocode):
<syntaxhighlight lang="c++">
enum EnumName
{
EnumConstantNameA,
EnumConstantNameB,
EnumConstantNameC,
EnumConstantNameD,

// etc...

// Note: it is not an error for the last
// EnumConstant to be followed by a ',' symbol,
// but it's generally not written
}
</syntaxhighlight>

Use the ''enum'' keyword to declare an enumeration; then you give it a name, and simply list a bunch of constants between the ''{'' and ''}''. As with variables, the names you chose for the enumeration and its constants should be meaningful to a human reader. Enumerations (sometimes simply called enums) are based on the ''int'' type; that is, the values of the defined constants are nothing but integers under the hood. By default, the value of the first constant is ''0'', and all the other constants have the value of the previous constant incremented by one. So, using pseudocode from the code box above, the values are:

<syntaxhighlight lang="c++">
enum EnumName
{
EnumConstantNameA, // = 0
EnumConstantNameB, // = 1 (previous + 1)
EnumConstantNameC, // = 2 (previous + 1)
EnumConstantNameD // = 3 (previous + 1)
}
</syntaxhighlight>

You are allowed to specify your own values for ''some or all'' of the enumerated constants. For those constants you didn't specify any value, the same (previous + 1) rule will be applied:
<syntaxhighlight lang="c++">
enum EnumName
{
EnumConstantNameA = -2, // = -2
EnumConstantNameB, // = -1 (previous + 1)
EnumConstantNameC = 15, // = 15
EnumConstantNameD // = 16 (previous + 1)
}
</syntaxhighlight>

Enumerations, even though based on integers, should be viewed as code constructs which define a ''new data type'', along with a set of values valid for the variables of that type. This is not entirely true, since variables of an enumerated type can be forced to store a value which is not defined in the corresponding list of enumerated constants, but let's ignore that for the moment. To declare such a variable, the same rules apply as for any other variable type: 
''EnumName'' ''variableName'';

Just like with normal constants (those defined using the ''const'' keyword) declared at global (script-level) scope, enumerated constants can be accessed by their name. For example, to initialize a enum-type variable, you can write: 
''EnumName'' ''variableName'' = ''EnumConstantName'';

However, for the reasons of code readability and clarity, when accessing enumerated constants it is often a good idea to include the name of the enumeration (''EnumName'') itself (especially when passing these values as parameters to functions), since ''EnumName'' often explains what is the common property used to group all the constants together in the first place. For this, the so-called scope resolution operator ''::'' is used: 
''EnumName'' ''variableName'' = ''EnumName''::''EnumConstantName'';

For example:
<syntaxhighlight lang="c++">
enum Direction
{
North,
West,
South,
East
}

// Later on:
Direction sideOfTheWorld = Direction::North;
</syntaxhighlight>

Another example:
<syntaxhighlight lang="c++">
// Let's assume there are only two types of items in your game

enum HealingPotion
{
Small = 10,
Medium = 30,
Large = 60,
Mega = 100
}

enum BodyArmor
{
Weak = 50,
Strong = 100
}

// Later on:
HealingPotion vial = HealingPotion::Small;
HealingPotion leatherArmor = BodyArmor::Weak;

// Or as a parameter to a hypothetical function
// void GivePlayerItems(HealingPotion potion, BodyArmor armor);

// Use:
GivePlayerItems(HealingPotion::Small, BodyArmor::Weak);

// Rather than:
GivePlayerItems(Small, Weak); // which is which?

// Alternatively:
GivePlayerItems(vial, leatherArmor);
</syntaxhighlight>

Although enumerated constants are grouped together under a single name, and can be accessed through that name using the scope resolution operator (''::''), they actually have a global (script-level) scope, so two constants in two different enums cannot share a name. For example, this is not allowed by the language:
<syntaxhighlight lang="c++">
enum HealingPotion
{
Small = 10,
Medium = 30,
Large = 60,
Mega = 100
}

enum BodyArmor
{
Small = 50, // compiler error
Large = 100 // compiler error
}
</syntaxhighlight>

==== Relation to the Integer Type ====

As discussed, enums are based on the ''int'' type. This allows them to be implicitly converted to integers if required, so they can be used in place of them. This is especially useful with functions that use "magic numbers". Implicit conversion ''from'' integers to enums, however, ''is not allowed''.

<syntaxhighlight lang="c++">
enum PowerLeverState
{
Undefined, // = 0
On, // = 1
Off // = 2
}

// Later on:
// Accepts a value of type PowerLeverState, even though it expects an int
SetLeverStuckState("Lever_Power", PowerLeverState::On, false);

// Also:
int stateValue = PowerLeverState::Off; // allowed; stateValue is now 2

// Wheres:
PowerLeverState state = 2; // NOT allowed!
</syntaxhighlight>

If you want to assign an ''int'' value to a enum-type variable, you have to explicitly convert it:
<syntaxhighlight lang="c++">
PowerLeverState state1 = PowerLeverState(2); // now state1 = PowerLeverState::Off

// Also:
int val = RandomInt(0, 2);
PowerLeverState state2 = PowerLeverState(val); // state2 takes a random value
</syntaxhighlight>

However, conversions like this should be done with care; although there are legitimate uses for them, conversions of this sort often indicate that your script can be better structured. When converting from integers, you run a risk of making your enum-type variables contain values other than those that have been defined as acceptable for their type:
<syntaxhighlight lang="c++">
PowerLeverState state1 = PowerLeverState(100); // state1 = 100. Now what?

// Also:
int val = -1;

// later on
PowerLeverState state2 = PowerLeverState(val); // state2 = -1. Could this cause problems?
</syntaxhighlight>

Although this compiles, and no error is displayed, depending on how your script is written, this may or may not cause problems. As conversions of this kind might happen accidentally, if your script relies on enums always having valid values, then there's a great chance that it will fail if a problematic enum-typed value comes along. So, always assume that such a value could be passed to your functions, and decide what to do if it happens. Often enough, you can simply ignore that case, and make your function do nothing and just silently end, but, if the underlying integer value is somehow used (for example, to cycle through all the possible values in a given enumeration), you need to check if the value provided is in the valid range first, and replace it with some acceptable value if it's not.

==== Using Enums to Define Binary Flags ====

The following section discusses slightly more advanced concepts, and also assumes you have the basic understanding of [[HPL2/ScriptReference/Control flow - Conditional Statements|conditional statements]]. You can skip it and come back later if you find it too hard to follow.

As it was discussed on the [[HPL2/ScriptReference/Types|Types]] page, the computer stores data in the form of ''bytes''. One byte contains 8 ''bits'', each of which can be either 0 or 1. This means that the computer encodes ''everything'' as sequences of zeros and ones (from simple data like integer numbers, floating point numbers, to srings, vectors, player attributes, Amnesia monsters, the image on this screen, etc.).

[http://farm9.staticflickr.com/8467/8371332748_e001db2c28_n.jpg ]

The binary system represents all numbers using only two symbols, 0 and 1. Each combination of zeros and ones encodes an integer number (for integer types) or maybe something else (for other types). For example, the binary number 00110101 depicted above represents the number 53. Now, we are not too concerned here with the details of ''how'' exactly all these are encoded (you can read about that elsewhere), but we are going to take a closer look at integer numbers, since this is what enum constants are under the hood. Let as first look at a single byte.

Because there are 256 different combinations of ones and zeros for 8 binary places, a byte can encode 256 different values at ''one time''. But, when used in a clever way, a byte can represent up to 8 different binary states ''simultaneously''. Such binary states (like on/off, pressed/depressed, lit/unlit, locked/unlocked etc.), can be encoded by correlating them to a specific position (specific bit) in a byte. For example, in the image below, a single byte is used to encode 6 different states related to the progress of a player through a level. Two of the bits are not used.

[http://farm9.staticflickr.com/8513/8371352462_ccf55f1631.jpg ]

In this example, knowing what is represented by each of the bits, you can read the value 0011 1010 to mean:
* 0 - (not used)
* 0 - (not used)
* 1 - the monster was slain by the player
* 1 - the key was found
* 1 - the light is lit
* 0 - the note was not found
* 1 - the switch is in the "on" state
* 0 - the lock is left unlocked

All of that information is encoded in ''a single byte''. This is one of the reasons to use flags - using them saves memory (a single byte vs several state variables). The other reason is that flags can be (and usually are) passed as parameters to functions, whereby several indicators of simple binary states are passed to the function simultaneously, through one variable. Flags often encode "settings"-like data, but should be used with care, as they can affect code readability and clarity.

''How to manipulate individual bits then?'' Well, by assigning integer numbers to variables, and by using binary logical operators, described below. However, manipulating bits while working with numbers in the decimal system is not very convenient. This is why programmers often use ''hexadecimal'' (HEX) numbers for such tasks. The reason is: there's a direct correspondence between HEX and binary numbers, as the table below shows, which makes it easy to deal with binary representations.

[http://farm9.staticflickr.com/8365/8371351734_f2f2795a54.jpg ]

As you can see, unlike the decimal number system, which represents all numbers using 10 different symbols (0-9), the HEX number system represents those same numbers using 16 different symbols (0-F). It just so happens that each of the HEX digits perfectly corresponds to one of all possible 4-bit combinations. Any one byte can thus be represented by 2 HEX digits - all you need to do is to refer to the table above, pick two hexadecimal digits, and write them together. To get the corresponding binary number, just replace the HEX digit with its binary equivalent from the table.

<pre>
Representing bytes using HEX system - some examples:

----------------------
HEX binary
----------------------
00 0000 0000
40 0100 0000
02 0000 0010
88 1000 1000
3A 0011 1010
FC 1111 1100
----------------------
</pre>

Note that to be able to do this, you ''don't have to'' understand the internal workings of the decimal, binary and hexadecimal number systems (although I encourage you to learn more on the web), nor do you have to know how to convert binary and HEX representations to and from decimal; all you need to know is which HEX digit corresponds to which binary sequence (and you can get that from the table).

Since HEX digits include both numerals and characters, the script language needs a way to distinguish HEX numerical literals from other numbers and variable names. So, the language provides the ''0x'' prefix - when you want to express a number in the HEX format, start by typing ''0x'' and then immediately (with no spaces in between) follow with your hex digits:
<syntaxhighlight lang="c++">
0x51 // A HEX number.
51 // A decimal number.

0x03 // A HEX number.
03 // A decimal integer 3.

0x5A // A HEX number.
5A // A compiler error?

0xD6 // A HEX number.
D6 // A variable? A function? A type name?
</syntaxhighlight>

On the [[HPL2/ScriptReference/Types|Types]] page, it was said that the ''int'' type takes up 4 bytes of memory. This means that a single integer can be used to represent 32 different binary states, of "flags", simultaneously. As with a single byte before, you don't have to use all of them. Also, since a 2-digit HEX number represents one byte, an 8-digit HEX number can be used to represent any 4-byte integer. You don't have to use all of the 8 digits, either -- if you use less than 8, the compiler will assume that the missing digits are all 0.

Finally, this can all be applied when specifying values for the enumerated constants, so that they can be used as binary flags. For the purpose of being flags, only binary values which contain a single bit set to 1 are used. In the table above, such values are highlighted in blue. There are only four of them, and they are all different representations for the numbers which are powers of two (just like, in decimal system, numbers like 1, 10, 100, 1000, etc., are all various powers of 10).

This way, each enum constant corresponds to a single bit in the binary number.
<syntaxhighlight lang="c++">
// Note: Although the constants are 4-byte integers, since only a single byte
// is used, all values will be represented as bytes

enum QuestCompletedFlags
{
None = 0x00, // = 0000 0000
DoorLocked = 0x01, // = 0000 0001
SwitchTurnedOn = 0x02, // = 0000 0010
NoteFound = 0x04, // = 0000 0100
LightsLit = 0x08, // = 0000 1000
KeyFound = 0x10, // = 0001 0000
MonsterSlain = 0x20 // = 0010 0000
}
</syntaxhighlight>

The enum flags defined in the code box above correspond to the possible states depicted earlier. Once the flags (constants) themselves are defined, they can be combined using the binary OR operator ''|'':

<syntaxhighlight lang="c++">
int questState = QuestCompletedFlags::DoorLocked | QuestCompletedFlags::LightsLit;

/* The value of questState is now (in binary):
-------------------------------------------------
DoorLocked: 0000 0001
| LightsLit: 0000 1000
= questState: 0000 1001 (the door is locked and the lights are lit) */
</syntaxhighlight>

The next code box shows how to represent the state which corresponds to the image below:
[http://farm9.staticflickr.com/8513/8371352462_ccf55f1631.jpg ]
<syntaxhighlight lang="c++">
// NOTE: "QuestCompletedFlags::" qualifiers ommitted for brevity.

int questState = SwitchTurnedOn | LightsLit | KeyFound | MonsterSlain;

/* The value of questState is now (in binary):
-------------------------------------------------
SwitchTurnedOn: 0000 0010
| LightsLit: 0000 1000
| KeyFound: 0001 0000
| MonsterSlain: 0010 0000
= questState: 0011 1010 */
</syntaxhighlight>

If you are familiar with the [[HPL2/ScriptReference/Control flow - Conditional Statements#using_logical_operators|boolean logical operators]], you'll be pleased to learn that the binary logical operators work pretty much the same way, only on individual bits. They take two numbers as input, and produce a third number based on the bits of the inputs provided.

'''The binary OR operator''' (''|'') sets a bit to ''1'' in the output if ''any'' of the corresponding bits in the inputs is ''1''. This is why it can be used to combine flags. 0011 | 1100 = 1111

'''The binary AND operator''' (''&'') sets a bit to ''1'' in the output ''only if both'' of the corresponding input bits are ''1''. For this reason, it can be used to check if a certain bit is set or not. 1110 & 0100 = 0100 -> if the result equals to the value of the tested flag, the bit was set 1110 & 0001 = 0000 -> if the result is 0 (zero), the bit was not set

'''The binary XOR operator''' (''^''), a.k.a exclusive-OR, sets a bit to ''1'' only if the corresponding input bits ''are different''. It can be used to invert all the bits. 0101 ^ 0000 = 0101 -> (nothing happens) 0101 ^ 1111 = 1010 -> inversion

So, how it all looks like in code? You've already seen how to set flags using the binary OR (''|'') operator.
The following code snippet demonstrates, continuing from the previous examples, how to check if the flag ''MonsterSlain'' was set in the ''questState'' variable:
<syntaxhighlight lang="c++">
if ((questState & QuestCompletedFlags::MonsterSlain) == QuestCompletedFlags::MonsterSlain)
{
// the monster was slain by the Player...
}
else
{
// the monster lives!
}

// questState: 0011 1010
// & MonsterSlain: 0010 0000
// = 0010 0000
</syntaxhighlight>

You can also check for several flags at once, by using AND (''&'') with binary numbers with multiple bits set to ''1''.
<syntaxhighlight lang="c++">
// the value of: 0x30 = 0011 0000
int checkState = QuestCompletedFlags::MonsterSlain | QuestCompletedFlags::KeyFound;

if ((questState & checkState) == checkState)
{
// both flags set
}
</syntaxhighlight>

Or, you can check all at once:
<syntaxhighlight lang="c++">
int checkState = 0x3F; // = 0011 1111

if ((questState & checkState) == checkState)
{
// all quests completed
}
</syntaxhighlight>

It is often convenient to include the "all flags set" value into the enumeration:
<syntaxhighlight lang="c++">
enum QuestCompletedFlags
{
None = 0x00, // = 0000 0000
DoorLocked = 0x01, // = 0000 0001
SwitchTurnedOn = 0x02, // = 0000 0010
NoteFound = 0x04, // = 0000 0100
LightsLit = 0x08, // = 0000 1000
KeyFound = 0x10, // = 0001 0000
MonsterSlain = 0x20, // = 0010 0000
AllDone = 0x3F // = 0011 1111
}

//later on:
int checkState = QuestCompletedFlags::AllDone;

if ((questState & checkState) == checkState)
{
// all quests completed
}
</syntaxhighlight>

Do not confuse binary logical operators (''|'', ''&'', and ''^''), which return a ''number'' as a result, with their boolean equivalents (''||'', ''&&'', and ''^^''), which return a ''boolean value'' (either ''true'' or ''false'').

HPL2/TDD

2025-01-19T21:34:17Z

BoxFigs: Added Areas link

{| class="wikitable" style="margin:auto;"
|+[[File:Tdd-header.jpg|250px|link=|Amnesia: The Dark Descent]]
|'''[[HPL2/Getting_started|<center>Getting started</center>]]'''
|Check out how to quickly get started creating custom content for Amnesia – The Dark Descent.
|-
|'''[[HPL2/TDD/Modding|<center>Modding</center>]]'''
|Create, organize and release your Amnesia mods
|-
|'''[[HPL2/TDD/Level Design|<center>Level Design</center>]]'''
|Work with the Level Editor and create immersive worlds
|-
|'''[[HPL2/Engine_Scripts|<center>Script Functions</center>]]'''
|See a list of all available script functions for Amnesia TDD
|-
|'''[[HPL2/TDD/Scripting|<center>Scripting</center>]]'''
|Some useful links for scripting
|-
|'''[[HPL2/TDD/Modeling|<center>Modeling</center>]]'''
|Import, export, add and modify 3D models for the game
|-
|'''[[HPL2/TDD/Entities|<center>Entities</center>]]'''
|Use the Model Editor to create interactive and dynamic objects
|-
|'''[[HPL2/TDD/Materials|<center>Materials</center>]]'''
|Use the Material Editor to combine texture maps to create materials
|-
|'''[[HPL2/TDD/Effects|<center>Effects</center>]]'''
|About effects: Lights, Billboards, Sounds and Particle Systems (effects like smoke, sparks, blood and fire)
|-
|'''[[HPL2/TDD/Areas|<center>Areas</center>]]'''
|Volumes and points placed in the Level Editor for scripting, water, ladders, ropes, and more
|-
|'''[[HPL2/Tutorials|<center>Tutorials</center>]]'''
|Step-by-step guides on a variety of topics, created by the community
|-
|'''[[HPL2/Third party tools|<center>Third-Party Tools</center>]]'''
|Useful developer tools, some of which are created by the community
|-
|'''[[HPL2/Glossary|<center>Glossary</center>]]'''
|Explanations for terms you may encounter
|}

[[Category:Entry pages]]
__NOTOC____NOEDITSECTION__

HPL2/AMFP/NewAreas

2025-01-19T21:16:39Z

BoxFigs: /* Infection */

AMFP features two new area types which weren't present in TDD.

== ColorGrading ==

This is an area which applies color correction when entered. It will show up as yellow in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| LookUpTable || File (.png) || || Determines the color grading map to use. Ready ones are located in <code>/textures/gradingmaps</code>.
|-
| FadeTime || Float || 1 || The time it takes for grading map to fade in/out after entering/leaving the area.
|-
|}

For information about creating custom grading textures, take a look at [[HPL2/AMFP/ColorGr|this guide]].

== Infection ==

This is a remnant of the unused infection system. It fills up the infection meter or lowers it when the player is inside the area. The area will show up as lime green in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| IncrementSpeed || Float || 20 || The speed at which the infection level rises or lowers. Negative values are also valid, which will heal the player's infection.
|-
| InfectionLevelLowerBound || Float || -1 || Lowest infection level the area can heal to.
|-
| InfectionLevelUpperBound || Float || 1 || Highest infection level the area can damage to. The player won't be able to get a higher infection level while standing in the area. Values 1-4. 4 and above lets the player die from infection. Infection drain is disabled when the bound has been hit and the player is still in the area.
|-
| TotalIncrementBound || Float || 0 || Disables the area when it has incremented the infection by a certain amount.
|-
| DisableOnLevelBoundHit || Bool || false || Disables the area if upper or lower level bound has been reached.
|-
|}

Note that infection is bounded to the ''middle'' of the level's range, not the true boundaries.

{|class=wikitable
! Level !! Middle Value
|-
| -1 || -37.5
|-
| 0 || 0
|-
| 1 || 12.5
|-
| 2 || 37.5
|-
| 3 || 62.5
|-
| 4 || 87.5
|-
|}

Using a negative bound value will never hit the level bound, so the area will not disable itself when DisableOnLevelBoundHit is true. This is because infection can never be less than 0.

For more information about the infection mechanic, see [[HPL2/AMFP/Infection| the Infection article]].

HPL2/AMFP/NewAreas

2025-01-19T21:01:55Z

BoxFigs: /* Infection */

AMFP features two new area types which weren't present in TDD.

== ColorGrading ==

This is an area which applies color correction when entered. It will show up as yellow in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| LookUpTable || File (.png) || || Determines the color grading map to use. Ready ones are located in <code>/textures/gradingmaps</code>.
|-
| FadeTime || Float || 1 || The time it takes for grading map to fade in/out after entering/leaving the area.
|-
|}

For information about creating custom grading textures, take a look at [[HPL2/AMFP/ColorGr|this guide]].

== Infection ==

This is a remnant of the unused infection system. It fills up the infection meter or lowers it when the player is inside the area. The area will show up as lime green in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| IncrementSpeed || Float || 20 || The speed at which the infection level rises or lowers. Negative values are also valid, which will heal the player's infection.
|-
| InfectionLevelLowerBound || Float || -1 || Lowest infection level the area can heal to.
|-
| InfectionLevelUpperBound || Float || 1 || Highest infection level the area can damage to. The player won't be able to get a higher infection level while standing in the area. Values 1-4. 4 and above lets the player die from infection. Infection drain is disabled when the bound has been hit and the player is still in the area.
|-
| TotalIncrementBound || Float || 0 || Disables the area when it has incremented the infection by a certain amount.
|-
| DisableOnLevelBoundHit || Bool || false || Disables the area if upper or lower level bound has been reached.
|-
|}

Note that infection is bounded to the ''middle'' of the level's range, not the true boundaries.

{|class=wikitable
! Level !! Middle Value
|-
| -1 || -37.5
|-
| 0 || 0
|-
| 1 || 12.5
|-
| 2 || 37.5
|-
| 3 || 62.5
|-
| 4 || 87.5
|-
|}

For more information about the infection mechanic, see [[HPL2/AMFP/Infection| the Infection article]].

HPL2/AMFP/NewAreas

2025-01-19T20:30:17Z

BoxFigs: /* Infection */

AMFP features two new area types which weren't present in TDD.

== ColorGrading ==

This is an area which applies color correction when entered. It will show up as yellow in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| LookUpTable || File (.png) || || Determines the color grading map to use. Ready ones are located in <code>/textures/gradingmaps</code>.
|-
| FadeTime || Float || 1 || The time it takes for grading map to fade in/out after entering/leaving the area.
|-
|}

For information about creating custom grading textures, take a look at [[HPL2/AMFP/ColorGr|this guide]].

== Infection ==

This is a remnant of the unused infection system. It fills up the infection meter or lowers it when the player is inside the area. The area will show up as lime green in the Level Editor.

{|class=wikitable
|+Variables
! Name !! Type !! Default !! Description
|-
| IncrementSpeed || Float || 20 || The speed at which the infection level rises or lowers. Negative values are also valid, which will heal the player's infection.
|-
| InfectionLevelLowerBound || Float || -1 || Lowest infection level the area can heal to.
|-
| InfectionLevelUpperBound || Float || 1 || Highest infection level the area can damage to. The player won't be able to get a higher infection level while standing in the area. Values 1-4. 4 and above lets the player die from infection. Infection drain is disabled when the bound has been hit and the player is still in the area.
|-
| TotalIncrementBound || Float || 0 || Disables the area when it has incremented the infection by a certain amount.
|-
| DisableOnLevelBoundHit || Bool || false || Disables the area if upper or lower level bound has been reached.
|-
|}

Note that infection is bounded to the ''middle'' of the level's range, not the true boundaries.

{|class=wikitable
! Level !! Middle Value
|-
| -1 || -37.5
|-
| 0 || -12.5
|-
| 1 || 12.5
|-
| 2 || 37.5
|-
| 3 || 62.5
|-
| 4 || 87.5
|-
|}

For more information about the infection mechanic, see [[HPL2/AMFP/Infection| the Infection article]].

HPL2/AMFP/Infection

2025-01-19T19:51:52Z

BoxFigs: /* Overview */

= Infection =

Infection is a mechanic which was cut from the final game, but it wasn't fully removed from it.

== Overview ==

The mechanic is quite similar to sanity from TDD. It is a meter which fills up in certain circumstances and plays visual and sound effects, which depend on the meter's value.

The infection meter is primarily changed by Infection areas. There are multiple of them placed in the game, but they all have been deactivated (which means that they can be restored). Infection areas can either increase or decrease infection. The only other functional method of changing infection (outside of scripting) is by standing in a Liquid area with the InfectionLevel variable set.

There are 4 levels of infection, all of which play increasingly noticeable screen effects (sepia, image trails, and radial blur).
{|class=wikitable
! Level !! Value Range (Check) !! Value (Set) !! Effects
|-
| 0 || 0 || 0 ||
|-
| 1 || 1-25 || 30 ||
|-
| 2 || 26-50 || 50 ||
|-
| 3 || 51-75 || 70 || Running disabled
|-
| 4 || 76-100 || 90 || Running disabled, -50% speed
|-
|}

Infection levels are calculated differently when going from level to value when checking infection level compared to setting infection level. Because of this quirk, setting infection to level 1 actually puts it in the level 2 range.

The meter goes down automatically after the player leaves the infected area. It will gradually fall to zero, unless the player has gathered above 80 infection; in that case, they will die after 2 seconds (unless "faux mode" is enabled). Interestingly, infection no longer decreases over time above 75, which leaves a tight margin of 5 infection points which won't kill the player but will not decrease.

Currently the only way to view the meter (aside from the audiovisual effects) is to press F1 in debug mode and turn on player info.

== Other evidence ==

According to these sections of '''game.cfg''', the infection system was a slightly modified version of the sanity mechanic.

<syntaxhighlight lang="xml">
<Infection
EventsFile = "misc/main_sanity_events.cfg"

MinTimeBetweenEvents = "300"
MaxEventSanity = "65"

MaxSanity_LongWait = "65"
MaxSanity_MedWait = "45"
MaxSanity_ShortWait = "25"

TimeBetween_LongWait = "270"
TimeBetween_MedWait = "180"
TimeBetween_ShortWait = "80"

MinExamineInfection = "50"

InfectionArea_CheckTimeMin = "1"
InfectionArea_CheckTimeMax = "2"
/>

<Player_Infection

HitZoomInSpeed = "3.5"
HitZoomOutSpeed = "0.6"
HitZoomInFOVMul = "0.06"
HitZoomInAspectMul = "0.15"

InfectionDecreaseSpeed = "0.75"
InfectionDecreaseLimitLevel = "3"

InfectionVeryHighLimit = "80"
InfectionEffectsStart = "35"

InfectionWaveAlphaMul = "1"
InfectionWaveSpeedMul = "1"

CheckEnemyNearOrSeenInterval = "0.3"

NearEnemyDecrease = "0.3"
NearCritterDecrease = "0.1"

StartSwayMinInfection = "15"
SwayMaxSavedPositions = "30"

HighInfectionLimitForDeathTimer = "80"
TimeUntilDeathAtHighInfection = "2"

LightLampMinInfectionIncrease = "0.1"
LightLampMaxInfectionIncrease = "5"

NumberOfInfectionLevels = "4"

InfectionLevelOneSpeedMultiplier = "1.0"
InfectionLevelTwoSpeedMultiplier = "1.0"
InfectionLevelThreeSpeedMultiplier = "1.0"
InfectionLevelFourSpeedMultiplier = "0.5"

MaxInfectionLevelAtWhichPlayerCanRun = "2"

GradientThresholdOffset = "1.1"
GradientFallofExponent = "8.0"
InfectionMapZoom = "0.95"

VomitEffectDuration ="3.0"

InfectionEffectGrowSpeed = "1"
/>
</syntaxhighlight>

However, in the game it uses a separate meter (which is visible via the aforementioned debug menu method).

The mentioned sanity events config file contains exactly the same data as TDD, which means that it wasn't used in the end.

Infection was supposed to increase near creatures, yet the config still has the old sanity property names:

<syntaxhighlight lang="xml">
NearEnemyDecrease = "0.3"
NearCritterDecrease = "0.1"
</syntaxhighlight>

The proper names for these are <code>NearEnemyIncrease</code> and <code>NearCritterIncrease</code>, although only CritterSpider increases infection, as a result of repurposed TDD code.

These property names were changed to replace "Sanity" with "Infection", but are entirely unused:

<syntaxhighlight lang="xml">
LightLampMinInfectionIncrease = "0.1"
LightLampMaxInfectionIncrease = "5"
</syntaxhighlight>

ManPig enemies have unused vomit animations and unused entity parameters, such as:

* DistanceAtWhichFleeingPigVomitAttacks
* MinimumTimeBetweenVomitAttacks
* MinTimeBeforeIgnoringPlayerAfterVomit

These seem to indicate that ManPigs would have attacked the player by vomiting, increasing the infection meter. The C++ source code shows that being vomited on would instantly set infection to the maximum level:

<syntaxhighlight lang="c++">
void cLuxPlayer::VomitDamage()
{
mfTimeSinceLastVomit = 0.0f;

/*if ( GetInfectionLevel() < 3 )
{
SetInfectionLevel( 3 );
}
else*/ if ( GetInfectionLevel() < 4 )
{
SetInfectionLevel( 4 );
}
}
</syntaxhighlight>

A particle effect called "''ps_pig_attack_vomit''" was also left in the game.

== Missing parts ==

When the infection is used in-game by enabling the infection areas, some errors get printed to the log:

<pre>
ERROR: Could not load sound 'infection_loop_1'
ERROR: Can't find sound 'infection_loop_1'!
ERROR: Couldn't create SoundEntity 'infection_drain_high.snt'
ERROR: Couldn't create SoundEntity 'infection_heartbeat.snt'
WARNING: Could not find language file entry 'InfectionHigh'
ERROR: Couldn't create SoundEntity 'infection_pant.snt'
</pre>

This indicates that some of the sound entity (.snt) files are missing. They don't have the raw sound files (.ogg) either.

Furthermore, the game displays an empty hint when player reaches level 4 of infection. Its lang file name is "InfectionHigh", which means that it can be remade and will display automatically. It is unknown if hints for other infection levels exist.

HPL2/Engine Scripts

2025-01-19T07:47:49Z

BoxFigs: Moved effect voice functions to sounds section as effect voices are purely audio, no visuals

{{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 in seconds 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 &in asString, string &in 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="c++">
string& StringSub(string &in 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 &in asString);
</syntaxhighlight>

Prints a string to the log file (''hpl.log'').

<syntaxhighlight lang="c++">
void AddDebugMessage(string &in asString, bool abCheckForDuplicates);
</syntaxhighlight>

Prints a line of text to the debug console at the bottom left of the screen. Debug mode must be enabled for the console messages to be visible.

#''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 &in asLevel, string &in 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 &in asName, int alVal);
void AddLocalVarInt(string &in asName, int alVal);
int GetLocalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarFloat(string &in asName, float afVal);
void AddLocalVarFloat(string &in asName, float afVal);
float GetLocalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetLocalVarString(string &in asName, const string &in asVal);
void AddLocalVarString(string &in asName, string &in asVal);
string& GetLocalVarString(string &in 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 &in asName, int alVal);
void AddGlobalVarInt(string &in asName, int alVal);
int GetGlobalVarInt(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarFloat(string &in asName, float afVal);
void AddGlobalVarFloat(string &in asName, float afVal);
float GetGlobalVarFloat(string &in asName);
</syntaxhighlight>

<syntaxhighlight lang="c++">
void SetGlobalVarString(string &in asName, const string &in asVal);
void AddGlobalVarString(string &in asName, string &in asVal);
string& GetGlobalVarString(string &in asName);
</syntaxhighlight>

===Particle Systems===

<syntaxhighlight lang="c++">
void PreloadParticleSystem(string &in asPSFile);
</syntaxhighlight>

Preloads a particle system.

#''asPSFile'' - The particle system file to load. Extension: .ps
<syntaxhighlight lang="c++">
void CreateParticleSystemAtEntity(string &in asPSName, string &in asPSFile, string &in 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 &in asPSName, string &in asPSFile, string &in 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 &in asName);
</syntaxhighlight>

Destroys a particle system.

#''asName'' - The internal name of the particle system

===Sounds & Music===

<syntaxhighlight lang="c++">
void PreloadSound(string &in asSoundFile);
</syntaxhighlight>

Preloads a sound.

#''asSoundFile'' - The sound file to load (extension .snt optional)

<syntaxhighlight lang="c++">
void PlayGuiSound(string &in asSoundFile, float afVolume);
</syntaxhighlight>

Plays a sound, not using 3D.

#''asSoundFile ''- the sound to play (extension .snt/.ogg optional)
#''afVolume ''- the volume of the sound

<syntaxhighlight lang="c++">
void PlaySoundAtEntity(string &in asSoundName, string &in asSoundFile, string &in asEntity, float afFadeTime, bool abSaveSound);
</syntaxhighlight>

Creates a sound at an entity.

#''asSoundName ''- internal name
#''asSoundFile ''- the sound to use (extension .snt optional)
#''asEntity ''- the entity to create the sound at. Using "Player" is effectively the same as <code>PlayGuiSound</code>, yet this function allows a looping sound to be saved
#''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 &in asSoundName, float afFadeTime, bool abPlayStart);
</syntaxhighlight>

Fades in a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds
#''abPlayStart ''- Play the sound defined in the <code><Start></code> section of the .snt before playing the main sound

<syntaxhighlight lang="c++">
void StopSound(string &in asSoundName, float afFadeTime);
</syntaxhighlight>

Fades out a sound.

#''asSoundName ''- internal name
#''afFadeTime ''- time in seconds, use 0 to immediately stop the sound

<syntaxhighlight lang="c++">
void PlayMusic(string &in asMusicFile, bool abLoop, float afVolume, float afFadeTime, int alPrio, bool abResume);
</syntaxhighlight>

Plays music.

#''asMusicFile ''- the music file to play (extension .ogg optional)
#''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 <code>StopMusic()</code>. 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 AddEffectVoice(string &in asVoiceFile, string &in asEffectFile, string &in asTextCat, string &in asTextEntry,
bool abUsePosition, string &in asPosEntity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

This adds a voice and an additional sound 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 sound effect to play
#''asTextCat ''- the category in the .lang file, usually "Voice"
#''asTextEntry ''- the text entry in the .lang file
#''abUsePosition ''- plays using 3D from the entity, or without 3D
#''asPosEntity ''- the entity at which the sound is played from
#''afMinDistance ''- minimum distance the voice is heard
#''afMaxDistance ''- maximum distance the voice is heard

<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 &in asFunc);
</syntaxhighlight>

Sets the function to be called when the EffectVoices are finished. Callback syntax: <code>void MyFunc()</code>

<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 &in asLightName, bool abVisible);
</syntaxhighlight>

Enables/disables lights.

#''asLightName ''- internal name
#''abVisible ''- determines the state of the light
<syntaxhighlight lang="c++">
void FadeLightTo(string &in 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 &in 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 &in asMusic, bool abLoopMusic, string &in asTextCat, string &in 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, usually "Ending"
#''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>

Shows the demo end screen. The background and UI elements are defined in demo.cfg, with the text using the entries in the "Demo" category of the .lang file.

<syntaxhighlight lang="c++">
void AutoSave();
</syntaxhighlight>

Creates an auto save file.

<syntaxhighlight lang="c++">
void CheckPoint(string &in asName, string &in asStartPos, string &in asCallback, string &in asDeathHintCat, string &in 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, usually "Hints"
#''asDeathHintEntry ''- the entry in the .lang file
<syntaxhighlight lang="c++">
void ChangeMap(string &in asMapName, string &in asStartPos, string &in asStartSound, string &in asEndSound);
</syntaxhighlight>

Loads another map after a 1.5 second fade out.

#''asMapName ''- the file to load
#''asStartPos ''- the name of the StartPos in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, int alRandomNum, string &in 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, usually "LoadingText"
#''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)

<syntaxhighlight lang="c++">
void UnlockAchievement(string &in asName);
</syntaxhighlight>

Unlocks the specified achievement. Only able to be used for the ending achievements.

#''asName'' - The name of the achievement. Only the following strings are valid:
::* Benefactor
::* Survivor
::* Sacrifice
::* Quitter
::* Egotist
::* Altruist
::* Vacillator

===Game Timer===

<syntaxhighlight lang="c++">
void AddTimer(string &in asName, float afTime, string &in 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 &in 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 &in 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 &in asTextCat, string &in asTextEntry, string &in 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++">
bool GetFlashbackIsActive();
</syntaxhighlight>

Checks whether a flashback is still in effect.

<syntaxhighlight lang="c++">
void StartPlayerSpawnPS(string &in 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. Example ''.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 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 &in 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. Not useful at all due to having a return type of <code>void</code> when it should be <code>bool</code>.

===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>

Resets the player's state, forcing them to stop interacting with objects. It also clears the inventory item to be used (as if it was double-clicked on in the inventory again) and dismounts the player from ladders.

<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.

<syntaxhighlight lang="c++">
void GiveSanityBoost();
</syntaxhighlight>

Boosts the player's sanity by a large amount depending on the current sanity.

{|class=wikitable
! Sanity !! New Sanity
|-
| 0-24 || 100
|-
| 25-49 || 90
|-
| 50-74 || 80
|-
| 75-100 || +5
|-
|}

<syntaxhighlight lang="c++">
void GiveSanityBoostSmall();
</syntaxhighlight>

Boosts the player's sanity by a small amount depending on the current sanity.

{|class=wikitable
! Sanity !! Sanity Bonus
|-
| 0-24 || +20
|-
| 25-49 || +15
|-
| 50-75 || +10
|-
| 75-100 || +5
|-
|}

<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 &in 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. If ''false'' and the damage would have left the player with less than 10 health, health is set to 10.

<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 FOVs

<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 FOVs

<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 MovePlayerForward(float afAmount);
</syntaxhighlight>

{{ReqVer|1.2}}

Moves the player forward. It needs to be called in a timer that updates 60 times / second.

<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 &in asEntityName, float afSpeedMul, float afMaxSpeed, string &in 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 &in 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.

# ''abX'' - Set lantern to be active (true) or inactive (false)
# ''abUseEffects'' - Play on/off sounds

<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 &in 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 &in asTextCategory, string &in 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 &in asTextCategory, string &in 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, usually "Hints"

<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="c++">
void SetPlayerPermaDeathSound(string &in asSound);
</syntaxhighlight>

{{ReqVer|1.2}}

Sets the sound played after the player dies when permadeath is active. Permadeath is only active when the game is launched with the <code>ptest</code> command line parameter. Only used for the post-death Suitor lines in ''Justine''.

#''asSound'' - The sound to be played after death. Expects a voice-type sound.

<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 &in asNameAndTextEntry, string &in 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 &in asNameAndTextEntry, string &in 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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Adds a quest to the player's journal under mementos. Completed quests cannot be readded.

#''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 &in asName, string &in asNameAndTextEntry);
</syntaxhighlight>

Completes a quest. If the quest has not been added, it's marked as complete anyway, preventing it from being added.

#''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 &in asName);
bool QuestIsAdded(string &in asName);
</syntaxhighlight>

Checks whether a quest is completed/added.

#''asName ''- the internal name of the quest

<syntaxhighlight lang="c++">
void SetNumberOfQuestsInMap(int alNumberOfQuests);
</syntaxhighlight>

Sets the number of quests in the map. Obsolete; formerly used to calculate a completion percentage when looking at a level door.

#''alNumberOfQuests ''- Amount of quests

<syntaxhighlight lang="c++">
void GiveHint(string &in asName, string &in asMessageCat, string &in asMessageEntry, float afTimeShown);
</syntaxhighlight>

Displays a hint on the player's screen.

#''asName ''- the internal name
#''asMessageCat ''- the category in the .lang file, usually "Hints"
#''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 &in asName);
void UnBlockHint(string &in asName);

</syntaxhighlight>

Blocking a hint prevents it from being shown. Blocked hints are included in savefiles, so they should persist between levels. Unblocking a hint allows it to be shown.

#''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.

<syntaxhighlight lang="c++">
void RemoveHint(string &in asName);
</syntaxhighlight>

Removes the hint from the list of already shown hints, allowing it to appear 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> reenables 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 &in asTextCategory, string &in asTextEntry, float afTime);
</syntaxhighlight>

Adds a message on the inventory screen. Used for feedback messages when failing to combine items.

#''asTextCategory ''- the category in the .lang file, usually "Inventory"
#''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 &in asName, string &in asType, string &in asSubTypeName, string &in 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 &in asName);
</syntaxhighlight>

Removes an item from the player's inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
bool HasItem(string &in asName);
</syntaxhighlight>

Checks whether the player has an item in his inventory.

#''asName ''- internal name

<syntaxhighlight lang="c++">
void GiveItemFromFile(string &in asName, string &in 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 &in asName, string &in asItemA, string &in asItemB, string &in 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 &in 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 &in asName, string &in asItem, string &in asEntity, string &in 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 of the callback
#''asItem ''- internal name of the item
#''asEntity ''- entity to be able to use the item on
#''asFunction ''- function to call
#''abAutoDestroy ''- determines whether the callback should be removed when the item is used

<syntaxhighlight lang="c++">
void RemoveUseItemCallback(string &in asName);
</syntaxhighlight>

Removes an item callback.

#''asName ''- internal name of the callback

===Entities===

====General====

<syntaxhighlight lang="c">
void SetEntityActive(string &in 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 &in asName);
</syntaxhighlight>

Checks whether an entity exists.

<syntaxhighlight lang="c">
void SetEntityCustomFocusCrossHair(string &in asName, string& asCrossHair);
</syntaxhighlight>

Changes the crosshair that is used when focusing an entity.

#''asName ''- internal name
#''asCrossHair ''- desired crosshair, can be:
::*Default (no crosshair)
::*Grab
::*Push
::*Ignite
::*Pick
::*LevelDoor
::*Ladder

<syntaxhighlight lang="c">
void CreateEntityAtArea(string &in asEntityName, string &in asEntityFile, string &in asAreaName, bool abFullGameSave);
</syntaxhighlight>

Creates an entity at an area. When creating an enemy though, it cannot chase properly along PathNodes (using for example <code>ShowEnemyPlayerPosition</code>).

#''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 &in asName, string &in 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 &in asName, string &in 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 &in asName, string &in asCallback);
</syntaxhighlight>

Calls a function when certain events occur with an entity. Callback syntax: <code>void MyFunc(string &in asEntity, string &in asType)</code>

<code>asType</code> values depend on entity type:

{|class=wikitable
! Entity Type !! asType Value
|-
| Object || Break
|-
| Lamp || OnIgnite
|-
| Item || OnPickup
|-
| Enemy || OnDeath
|-
| Enemy_Grunt Enemy_Manpig || OnAutoDisabled
|-
|}

<syntaxhighlight lang="c">
void SetEntityConnectionStateChangeCallback(string &in asName, string &in 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 &in asName, bool abDisabled);
</syntaxhighlight>

Disallows interaction with an entity.

<syntaxhighlight lang="c">
void BreakJoint (string &in 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 &in asParentName, string &in asChildName, string &in asFunction, bool abDeleteOnCollide, int alStates);
</syntaxhighlight>

Calls a function when two entities 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 &in asParentName, string &in asChildName);
</syntaxhighlight>

Removes an EntityCollideCallback. Asterix (<nowiki>*</nowiki>) not supported in ''asChildName''.

<syntaxhighlight lang="c">
bool GetEntitiesCollide(string &in asEntityA, string &in asEntityB);
</syntaxhighlight>

Checks whether two entities 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 &in 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 &in 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 &in asName, bool abX);
</syntaxhighlight>

Activates/deactivates the physics of a prop, setting the mass to 0. Setting as true will make entities static in midair.

<syntaxhighlight lang="c">
bool GetPropIsInteractedWith(string &in asName);
</syntaxhighlight>

Checks whether a prop is interacted with.

<syntaxhighlight lang="c">
void RotatePropToSpeed(string &in asName, float afAcc, float afGoalSpeed, float afAxisX, float afAxisY, float afAxisZ, bool abResetSpeed, string &in 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 &in asName);
</syntaxhighlight>

Stops all movement of a prop.

<syntaxhighlight lang="cpp">
void AddAttachedPropToProp(string &in asPropName, string &in asAttachName, string &in asAttachFile, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Attaches a prop to another prop.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName, string &in 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 <code>AddAttachedPropToProp</code>.

#''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 <code>AddEntityCollideCallback</code>, 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 &in asPropName, string &in asAttachName);
</syntaxhighlight>

Detaches a prop from a prop.

<syntaxhighlight lang="cpp">
void SetPropHealth(string &in asName, float afHealth);
void AddPropHealth(string &in asName, float afHealth);
float GetPropHealth(string &in asName);
</syntaxhighlight>

Modifies/returns the health of a prop.

<syntaxhighlight lang="cpp">
void ResetProp(string &in asName);
</syntaxhighlight>

Resets a prop's state to the original one when the map was loaded.

<syntaxhighlight lang="cpp">
void PlayPropAnimation(string &in asProp, string &in asAnimation, float afFadeTime, bool abLoop, string &in 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 ''- Fade time between current and new animations
#''abLoop ''- determines whether the animation loops
#''asCallback ''- function to call

<syntaxhighlight lang="cpp">
void AddPropForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddPropImpulse(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyForce(string &in asName, float afX, float afY, float afZ, string &in asCoordSystem);
void AddBodyImpulse(string &in asName, float afX, float afY, float afZ, string &in 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, "local" or "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 &in asName, string &in asPropName, string &in asRopeName, bool abInteractOnly, float afSpeedMul, float afToMinSpeed, float afToMaxSpeed, bool abInvert, int alStatesUsed);
</syntaxhighlight>

Connects a prop with the movement of a rope (i.e. turn a wheel to move a rope). For Levers, the rope only moves when the Lever is at the min, max, or middle.

#''asName''- The name of the connection
#''asPropName'' - The name of the prop; can be a Lever or Wheel
#''asRopeName'' - The name of the rope
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''afSpeedMul'' - Speed multiplier of how quickly the rope moves
#''afToMinSpeed'' - The slowest the rope can move
#''afToMaxSpeed'' - The fastest the rope can move
#''abInvert'' - Whether to invert the direction the rope moves
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void InteractConnectPropWithMoveObject(string &in asName, string &in asPropName, string &in asMoveObjectName, bool abInteractOnly, bool abInvert, int alStatesUsed);
</syntaxhighlight>

This one should only be used if there must be an exact correspondence to prop "amount" and the MoveObject open amount. It is best used for Wheel-door connections, where the MoveObject moves continuously along with the Wheel. For Levers, the MoveObject only moves when the Lever is at the min, max, or middle.

#''asName'' - The name of the connection
#''asPropName'' - The entity that controls the movement; can be a Lever or Wheel
#''asMoveObject'' - The MoveObject to move
#''abInteractOnly'' - If the connection is only affected by interacting with the prop directly
#''abInvert'' - If the state is inverted, making the MoveObject move in the opposite direction
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)

<syntaxhighlight lang="cpp">
void ConnectEntities(string &in asName, string &in asMainEntity, string &in asConnectEntity, bool abInvertStateSent, int alStatesUsed, string &in asCallbackFunc);
</syntaxhighlight>

Connects two entities together so that changing the state of the main entity changes the state of the connected entity.

{|class=wikitable
! Entity Type !! Max State (1) !! Min State (-1)
|-
| Lamp || Lit || Unlit
|-
| MoveObject || Open || Close
|-
| SwingDoor
|rowspan=2| Locked
|rowspan=2| Unlocked
|-
| Chest
|-
| Button || Switched on || Switched off
|-
| Lever
|rowspan=2| Unstuck
|rowspan=2| Stuck (at min)
|-
| Wheel
|-
|}

#''asName'' - The name of the connection
#''asMainEntity'' - The entity that causes the change; can be a Lever, Wheel, Button, or Photocell
#''asConnectEntity'' - The entity that is affected by the change
#''abInvertStateSent'' - If the state is inverted, making the connected entity change to the opposite state
#''alStatesUsed'' - The state to use, ignoring the other (1=max only, -1=min only, 0=both)
#''asCallbackFunc'' - The name of the connection callback

Callback syntax: <code>void MyFunc(string &in asConnectionName, string &in asMainEntity, string &in asConnectEntity, int alState)</code> alState is what is sent to connection entity and will be inverted if abInvertStateSent = true!

====Lamps====

<syntaxhighlight lang="cpp">
void SetLampLit(string &in asName, bool abLit, bool abEffects);
</syntaxhighlight>

Turns a lamp on or off.

#''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 lit/unlit

====Doors====

<syntaxhighlight lang="cpp">
void SetSwingDoorLocked(string &in asName, bool abLocked, bool abEffects);
</syntaxhighlight>

Locks a SwingDoor.

#''asName ''- Name of the door
#''abLocked'' - Locked/unlocked
#''abEffects ''- If sounds are played when the door is locked/unlocked

<syntaxhighlight lang="cpp">
void SetSwingDoorClosed(string &in asName, bool abClosed, bool abEffects);
</syntaxhighlight>

Closes a SwingDoor.

#''asName ''- Name of the door
#''abClosed'' - Closed/open
#''abEffects ''- If sounds are played when the door is closed/opened

<syntaxhighlight lang="cpp">
bool GetSwingDoorLocked(string &in asName);
bool GetSwingDoorClosed(string &in asName);
</syntaxhighlight>

Checks whether a swing door is locked/closed.

<syntaxhighlight lang="cpp">
void SetSwingDoorDisableAutoClose(string &in asName, bool abDisableAutoClose);
</syntaxhighlight>

Deactivates the "auto-close" when a door is nearly closed.

<syntaxhighlight lang="cpp">
int GetSwingDoorState(string &in 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 &in asName, bool abLocked);
</syntaxhighlight>

Locks a level door. Note that level doors are NOT swing doors.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedSound(string &in asName, string &in asSound);
</syntaxhighlight>

Determines which sound is played when interacting with a locked level door.

<syntaxhighlight lang="cpp">
void SetLevelDoorLockedText(string &in asName, string &in asTextCat, string &in 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 &in 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 &in 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 deceleration occurs.
#''abResetSpeed ''- Set to ''true'' if the prop's speed should be reset before performing the movement, else the prop will accelerate from its current speed to afMaxSpeed.

====Levers, wheels and buttons====

<syntaxhighlight lang="cpp">
void SetPropObjectStuckState(string &in asName, int alState);
void SetWheelStuckState(string &in asName, int alState, bool abEffects);
void SetLeverStuckState(string &in 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 &in 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 &in asName, bool abX);
void SetLeverInteractionDisablesStuck(string &in asName, bool abX);
</syntaxhighlight>

Allows the player to make a wheel/lever unstuck when interacted with.

<syntaxhighlight lang="cpp">
int GetLeverState(string &in asName);
</syntaxhighlight>

Returns the state of the lever. 0 = not stuck, 1 = at max, -1 = at min

<syntaxhighlight lang="cpp">
void SetMultiSliderStuckState(string &in asName, int alStuckState, bool abEffects);
</syntaxhighlight>

Makes a MultiSlider stuck in a certain state.

<syntaxhighlight lang="cpp">
void SetMultiSliderCallback(string &in asName, string &in 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 &in asName, bool abSwitchedOn, bool abEffects);
</syntaxhighlight>

====Sticky areas====

<syntaxhighlight lang="cpp">
void SetAllowStickyAreaAttachment(bool abX);
</syntaxhighlight>

Allows entities to stick to a StickyArea.

<syntaxhighlight lang="cpp">
void AttachPropToStickyArea(string &in asAreaName, string &in asProp);
void AttachBodyToStickyArea(string &in asAreaName, string &in asBody);
</syntaxhighlight>

Attaches a prop/body to a StickyArea.

<syntaxhighlight lang="cpp">
void DetachFromStickyArea(string &in asAreaName);
</syntaxhighlight>

Detaches everything from a StickyArea.

====NPCs====

<syntaxhighlight lang="cpp">
void SetNPCAwake(string &in asName, bool abAwake, bool abEffects);
</syntaxhighlight>

Wakes/sleeps a NPC.

#''asName'' - The name of the NPC
#''abAwake'' - ''true'' to awaken, ''false'' to sleep
#''abEffects'' - Play the "Awake" or "Sleep" animations

<syntaxhighlight lang="cpp">
void SetNPCFollowPlayer(string &in asName, bool abX);
</syntaxhighlight>

Sets a NPC's head to follow the player's movements.

====Enemies====

<syntaxhighlight lang="cpp">
void SetEnemyDisabled(string &in asName, bool abDisabled);
</syntaxhighlight>

Disables an enemy.

<syntaxhighlight lang="cpp">
void SetEnemyIsHallucination(string &in 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 &in asName, bool abPlaySound);
</syntaxhighlight>

Instantly fades an enemy to smoke.

<syntaxhighlight lang="cpp">
void ShowEnemyPlayerPosition(string &in 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 &in 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 &in asName, string &in asNodeName, float afWaitTime, string &in 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. If 0, randomized between 1-3.
#''asAnimation'' - The animation the enemy uses when reaching the path node

<syntaxhighlight lang="cpp">
void ClearEnemyPatrolNodes(string &in 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 Tesla ManPig 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 Tesla ManPig 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 Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string &in asName);
</syntaxhighlight>

{{ReqVer|1.3}}

Forces a Tesla ManPig 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.

#''asName'' - Internal name of the enemy

Possible states for all enemies:
*Idle
*Wait
*Patrol
*Investigate
*Alert
*Search
*Hurt
*Hunt
*HuntPause
*HuntWander
*AttackMeleeShort
*AttackMeleeLong
*BreakDoor
*Dead

Waterlurker-only states:
*GoHome
*Eat

ManPig-only states:
*Flee
*Stalk
*Track

Unused states:
*AttackRange

HPL2/AMFP/ScriptFunctions

2025-01-19T07:31:53Z

BoxFigs: /* Player */

== 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.

=== General ===

<syntaxhighlight lang="cpp">
void CheckPoint(string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry, bool abKeepPlayerInLimbo);
</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
# ''asStartPos'' - The name of the PlayerStartArea to respawn at
# ''asCallback'' - The name of the callback function to run
# ''asDeathHintCat'' - The name of the .lang file category
# ''asDeathHintEntry'' - The name of the .lang file entry
# ''abKeepPlayerInLimbo'' - 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.

=== Particle Systems ===

<syntaxhighlight lang="c++">
void SetParticleSystemActive(string& asName, bool abActive);
</syntaxhighlight>

Pauses a particle system in its current frame. The paused particle system remains frozen at this frame until reactivated or destroyed.

# ''asName'' - The name of the particle system
# ''abActive'' - False to pause, true to unpause

<syntaxhighlight lang="c++">
void DestroyParticleSystemInstantly(string& asName);
</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.

#''asName'' - The internal name of the particle system

=== Sounds ===

<syntaxhighlight lang="c++">
void AddEffectVoice2(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with two 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with three 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with four 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with five 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - 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 AddEffectVoice5(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, string& asText6Entry, float afText6Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with six 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - The time to wait until the fifth subtitle starts
# ''asText6Entry'' - The sixth .lang subtitle entry
# ''afText6Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, string& asText6Entry, float afText6Delay, string& asText7Entry, float afText7Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with seven 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - The time to wait until the fifth subtitle starts
# ''asText6Entry'' - The sixth .lang subtitle entry
# ''afText6Delay'' - The time to wait until the sixth subtitle starts
# ''asText7Entry'' - The seventh .lang subtitle entry
# ''afText7Delay ''- 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

=== Screen Effects ===

<syntaxhighlight lang="cpp">
void ShowScreenImage(string& asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</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()]].

# ''asImageName'' - The image file to show. Does not have to be pow2 (although it gives a warning if not)
# ''afX''- 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.
# ''afY''- The Y position of the top left corner, starting from the center of the screen.
# ''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'' - How long, in seconds, the image displays. This does not include fade times
# ''afFadeIn'' - How long, in seconds, the fade in spends
# ''afFadeOut'' - 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">
bool GetJournalDisabled();
</syntaxhighlight>

Returns if the journal is currently disabled.

<syntaxhighlight lang="cpp">
void SetJournalDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open their journal.

# ''abX'' - True to disable, false to enable again

=== Player ===

<syntaxhighlight lang="c++">
void SetLanternFlickerActive(bool abX);
</syntaxhighlight>

Enables/disables the flicker effect for the lantern's light.

# ''abX'' - True to flicker, false to not flicker

<syntaxhighlight lang="c++">
void SetPlayerInfection(float afInfection);
</syntaxhighlight>

Sets the [[HPL2/AMFP/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 50 will affect the player's ability to move. Infection level above 80 will kill the player after a 2 second delay. Infection slowly decreases over time, unless above 75. This function replaces TDD's ''SetPlayerSanity''.

# ''afInfection'' - The level of infection to set

<syntaxhighlight lang="c++">
void AddPlayerInfection(float afInfection);
</syntaxhighlight>

Adds an amount of infection to the player's current amount. This function replaces TDD's ''AddPlayerSanity''.

# ''afInfection'' - 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="cpp">
void GiveInfectionDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Increases the infection of the player. This function replaces TDD's ''GiveSanityDamage''.

# ''afAmount'' - Amount of infection damage done
# ''abUseEffect'' - Determines whether a sound effect is played when the infection damage is dealt

<syntaxhighlight lang="c++">
void SetInfectionFauxMode(bool abFauxMode);
</syntaxhighlight>

Enable/disable "faux mode" for infection. In faux mode, the player cannot die of infection and infection sounds don't play.

<syntaxhighlight lang="c++">
void FadePlayerPitchTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Moves the player's pitch (up and down rotation).

# ''afX'' - The target pitch to move towards. 0 = straight forward. Clamped to range: -70 to +70.
# ''afSpeedMul'' - The speed multiplier of the movement. A low value makes a slow change.
# ''afMaxSpeed'' - The max speed of the movement.

<syntaxhighlight lang="c++">
void SetPlayerUsesDragFootsteps(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 ===

==== General ====

<syntaxhighlight lang="c++">
bool GetEntityActive(string& asName);
</syntaxhighlight>

Returns whether an entity in the level is active or not.

# ''asName'' - The entity to check

<syntaxhighlight lang="c++">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Creates an entity at an area with the specified offsets and rotation. This function replaces TDD's ''CreateEntityAtArea''.

# ''asEntityName'' - The internal name of the created entity
# ''asEntityFile'' - The file for the entity (extension .ent)
# ''asAreaName'' - The area to create entity at
# ''abFullGameSave'' - Determines whether an entity "remembers" its state
# ''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

==== Props ====

<syntaxhighlight lang="c++">
void SetPhysicsAutoDisable(string& asName, bool abAutoDisable);
</syntaxhighlight>

If physics bodies will automatically sleep (become inactive and stop moving). Only used on chandeliers in the campaign.

# ''asName'' - The prop to affect
# ''abAutoDisable'' - Whether physics auto disables or not

<syntaxhighlight lang="c++">
void AttachPropToBone(string& asChildEntityName, string& asParentEntityName, string& asParentBoneName, float fPosX, float fPosY, float fPosZ, float fRotX, float fRotY, float fRotZ);
</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.

# ''asChildEntityName'' - The prop to attach
# ''asParentEntityName'' - The entity that holds the bone to attach to
# ''asParentBoneName'' - The bone within the entity to attach to
# ''afPosX'' - Offset along the X axis
# ''afPosY'' - Offset along the Y axis
# ''afPosZ'' - 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& asChildEntityName);
</syntaxhighlight>

Detaches an attached prop. Note: When detached, physics are not automatically enabled on the prop.

# ''asChildEntityName'' - The attached prop

<syntaxhighlight lang="c++">
void AttachAreaToProp(string& asAreaName, string& asProp, int alBody);
</syntaxhighlight>

Attaches an area to a prop. Originally used to attach a liquid area to a movable water plane entity in the sewers map.

# ''asAreaName'' - The area to attach
# ''asProp'' - The prop to attach area to
# ''alBody'' - The ID of the physics body of the prop to attach to

<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 prop

<syntaxhighlight lang="c++">
void PlayCurrentAnimation(string& asProp, float afFadeTime, bool abLoop);
</syntaxhighlight>

Fades in the active animation, optionally allowing it to loop.

# ''asProp'' - The name of the prop
# ''afFadeTime'' - The fade time between animations
# ''abLoop'' - If the animation should be looped

<syntaxhighlight lang="c++">
void PauseCurrentAnimation(string& asProp, float afFadeTime);
</syntaxhighlight>

Fades out the active animation.

# ''asProp'' - The name of the prop
# ''afFadeTime'' - The fade time between animations

<syntaxhighlight lang="c++">
void SetPropAnimationSpeed(string& asProp, float afSpeed);
</syntaxhighlight>

Set the speed of the animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The prop that is being animated
# ''afSpeed'' - The new animation speed

<syntaxhighlight lang="c++">
void SetPropAnimationPosition(string& asProp, float afPos);
</syntaxhighlight>

Jumps to a specific point in an animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The prop that is being animated
# ''afPos'' - The time within the animation, in seconds, to jump to

==== Lamps ====

<syntaxhighlight lang="c++">
void SetLampFlickerActive(string& asName, bool abActive);
</syntaxhighlight>

Enables a flickering effect on a Lamp.

# ''asName'' - The lamp entity
# ''abActive'' - Whether to enable flicker

<syntaxhighlight lang="c++">
void FadeLampTo(string& asName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Fades a Lamp'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.

# ''asName'' - The lamp to change
# ''afR'' - Red value (appropriate values are 0 - 10)
# ''afG'' - Green value (appropriate values are 0 - 10)
# ''afB'' - Blue value (appropriate values are 0 - 10)
# ''afA'' - Alpha value (has no effect?)
# ''afRadius'' - The new radius to use (affects illumination strength)
# ''afTime'' - Time in seconds until the light properties have changed

<syntaxhighlight lang="c++">
void SetLampCanBeLitByPlayer(string& asName, bool abX);
</syntaxhighlight>

Enables/disables the player's ability to light a lamp.

# ''asName'' - The name of the Lamp
# ''abX'' - State to set

==== Doors ====

<syntaxhighlight lang="c++">
void SetSwingDoorOpenAmount(string& asName, float afOpenAmount, float afDuration, bool abOpenTowardsMaxAngle);
</syntaxhighlight>

Sets the open amount for a SwingDoor.

# ''asName'' - The SwingDoor entity
# ''afOpenAmount'' - The new amount state to set. Range: 0 - 1
# ''afDuration'' - The time in seconds until the door has changed state
# ''abOpenTowardsMaxAngle'' - If the door will swing to its max angle instead of its min angle

==== Buttons ====

<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOn(string& asName, bool abCanBeSwitchedOn);
</syntaxhighlight>

Changes whether a Button can be switched from off to on.

# ''asName'' - The Button entity
# ''abCanBeSwitchedOn'' - Whether it can be switched on

<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOff(string& asName, bool abCanBeSwitchedOff);
</syntaxhighlight>

Changes whether a Button can be switched from on to off.

# ''asName'' - The Button entity
# ''abCanBeSwitchedOff'' - Whether it can be switched off

==== PhoneBoxes ====

<syntaxhighlight lang="c++">
void StartPhoneRinging(string& asName);
</syntaxhighlight>

Enables a PhoneBox to start ringing. A ringing phone box can be interacted with to play some audio files. After interacting, the phone will stop ringing.

# ''asName'' - The PhoneBox entity

<syntaxhighlight lang="c++">
void StopPhoneRinging(string& asName);
</syntaxhighlight>

Stops a ringing PhoneBox.

# ''asName'' - The PhoneBox entity

<syntaxhighlight lang="c++">
void HangUpPhone(string& asName);
</syntaxhighlight>

Hangs up a PhoneBox.

# ''asName'' - The PhoneBox entity

==== Enemies ====

<syntaxhighlight lang="c++">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation, bool abLoopAnimation);
</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.

# ''asName'' - The name of the enemy
# ''asNodeName'' - Internal name of path node
# ''afWaitTime'' - The time, in seconds, the enemy waits at this node before continuing. Note: A time of 0 instead randomizes between 1 and 3 seconds, so use 0.01 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.
# ''abLoopAnimation'' - If the animation should be looped

<syntaxhighlight lang="c++">
void SetEnemyMoveType(string& asName, string& asMoveType);
</syntaxhighlight>

Changes how an enemy moves.

# ''asName'' - The name of the enemy
# ''asMoveType'' - The type to change to. Can be "WalkBiped", "RunBiped", "ChargeBiped", "Idle"

<syntaxhighlight lang="c++">
void SetManPigType(string& asName, string& asManPigType);
</syntaxhighlight>

Sets the personality type for a ManPig enemy. Non-functional; left over from an earlier state of development. Only "Freddy" is used as the type, but supposedly it should also accept "Rod" and "Jane".

# ''asName'' - The ManPig enemy.
# ''asManPigType'' - 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"
! Enemy Agent Personality Type !! Primary Behavioral Traits
|-
| Rod ||
*Will maintain a 'safe' distance to the player-character.
*If 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 SetTeslaPigFadeDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should fade the player's view in and out.

#''asName ''- Internal name of the enemy
#''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should play the proximity sounds.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string& asName);
</syntaxhighlight>

Forces a Tesla ManPig to be visible for a short time.

#''asName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
void PlayEnemyAnimation(string& asEnemyName, string& asAnimName, bool abLoop, float afFadeTime);
</syntaxhighlight>

Plays a specific animation for an enemy.

# ''asEnemyName'' - Internal name of the enemy (asterisk is allowed)
# ''asAnimName'' - The name of an animation registered to the enemy
# ''abLoop'' - Whether the animation loops
# ''afFadeTime'' - The fade time between animations

<syntaxhighlight lang="cpp">
void PlayScriptedAnimation(string& asName, string& asAnimationName, bool abLoopAnimation);
</syntaxhighlight>

Plays an animation that has been added to an entity through the Model Editor. Similar to ''PlayEnemyAnimation''.

# ''asName'' - Internal name of the enemy
# ''asAnimationName'' - The animation name
# ''abLoopAnimation'' - Whether to loop the animation or play it only once

<syntaxhighlight lang="c++">
void ChangeEnemyPose(string& asName, string& asPoseType);
</syntaxhighlight>

Changes the pose for an enemy. Can be either "Biped" or "Quadruped".

# ''asName'' - Internal name of the enemy
# ''asPoseType'' - The pose to change to

<syntaxhighlight lang="c++">
void ForceEnemyWaitState(string& asName);
</syntaxhighlight>

Forces the enemy's AI to change its 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.

# ''asName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
void SendEnemyTimeOut(string& asName, float afTimeOut );
</syntaxhighlight>

Forces the enemy's AI to change its state to "TimeOut", which forces the enemy to pause.

# ''asName'' - Internal name of the enemy
# ''afTimeOut'' - The length of the time out

<syntaxhighlight lang="c++">
void StopAnimationAndContinue(string& asName, float afTimeOut);
</syntaxhighlight>

Forces the enemy to stop its patrol animation for the specified amount of time.

# ''asName'' - Internal name of the enemy
# ''afTimeOut'' - The length of the time out

<syntaxhighlight lang="c++">
void SetEnemyBlind(string& asName, bool abX);
</syntaxhighlight>

Sets whether the enemy can see the player if they are within visible range.

# ''asName'' - Internal name of the enemy
# ''abX'' - Whether enemy is blind

<syntaxhighlight lang="c++">
void SetEnemyDeaf(string& asName, bool abX);
</syntaxhighlight>

Sets whether the enemy can hear the player make sound if they are within audible range.

# ''asName'' - Internal name of the enemy
# ''abX'' - Whether enemy is deaf

<syntaxhighlight lang="c++">
bool GetPlayerCanSeeEnemy(string& asEnemyName);
</syntaxhighlight>

Returns whether the enemy is within visible range of the player.

# ''asEnemyName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
float GetEnemyPlayerDistance(string& asEnemyName);
</syntaxhighlight>

Returns the distance (in meters) between the enemy and the player.

# ''asEnemyName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
int GetEnemyState(string& asName);
</syntaxhighlight>

Returns the enemy's current state as an integer.

# ''asName'' - Internal name of the enemy

HPL2/AMFP/ScriptFunctions

2025-01-19T07:30:43Z

BoxFigs: /* Player */

== 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.

=== General ===

<syntaxhighlight lang="cpp">
void CheckPoint(string& asName, string& asStartPos, string& asCallback, string& asDeathHintCat, string& asDeathHintEntry, bool abKeepPlayerInLimbo);
</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
# ''asStartPos'' - The name of the PlayerStartArea to respawn at
# ''asCallback'' - The name of the callback function to run
# ''asDeathHintCat'' - The name of the .lang file category
# ''asDeathHintEntry'' - The name of the .lang file entry
# ''abKeepPlayerInLimbo'' - 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.

=== Particle Systems ===

<syntaxhighlight lang="c++">
void SetParticleSystemActive(string& asName, bool abActive);
</syntaxhighlight>

Pauses a particle system in its current frame. The paused particle system remains frozen at this frame until reactivated or destroyed.

# ''asName'' - The name of the particle system
# ''abActive'' - False to pause, true to unpause

<syntaxhighlight lang="c++">
void DestroyParticleSystemInstantly(string& asName);
</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.

#''asName'' - The internal name of the particle system

=== Sounds ===

<syntaxhighlight lang="c++">
void AddEffectVoice2(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with two 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with three 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with four 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with five 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - 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 AddEffectVoice5(string& asVoiceFile, string& asEffectFile, string& asTextCat, string& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, string& asText6Entry, float afText6Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with six 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - The time to wait until the fifth subtitle starts
# ''asText6Entry'' - The sixth .lang subtitle entry
# ''afText6Delay'' - 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& asTextEntry, float afTextDelay, string& asText2Entry, float afText2Delay, string& asText3Entry, float afText3Delay, string& asText4Entry, float afText4Delay, string& asText5Entry, float afText5Delay, string& asText6Entry, float afText6Delay, string& asText7Entry, float afText7Delay, bool abUsePostion, string& asPosEnitity, float afMinDistance, float afMaxDistance);
</syntaxhighlight>

Plays an audio file with seven 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
# ''asTextEntry'' - The first .lang subtitle entry
# ''afTextDelay'' - The time to wait until the first subtitle starts
# ''asText2Entry'' - The second .lang subtitle entry
# ''afText2Delay'' - The time to wait until the second subtitle starts
# ''asText3Entry'' - The third .lang subtitle entry
# ''afText3Delay'' - The time to wait until the third subtitle starts
# ''asText4Entry'' - The fourth .lang subtitle entry
# ''afText4Delay'' - The time to wait until the fourth subtitle starts
# ''asText5Entry'' - The fifth .lang subtitle entry
# ''afText5Delay'' - The time to wait until the fifth subtitle starts
# ''asText6Entry'' - The sixth .lang subtitle entry
# ''afText6Delay'' - The time to wait until the sixth subtitle starts
# ''asText7Entry'' - The seventh .lang subtitle entry
# ''afText7Delay ''- 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

=== Screen Effects ===

<syntaxhighlight lang="cpp">
void ShowScreenImage(string& asImageName, float afX, float afY, float afScale, bool abUseRelativeCoordinates, float afDuration, float afFadeIn, float afFadeOut);
</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()]].

# ''asImageName'' - The image file to show. Does not have to be pow2 (although it gives a warning if not)
# ''afX''- 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.
# ''afY''- The Y position of the top left corner, starting from the center of the screen.
# ''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'' - How long, in seconds, the image displays. This does not include fade times
# ''afFadeIn'' - How long, in seconds, the fade in spends
# ''afFadeOut'' - 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">
bool GetJournalDisabled();
</syntaxhighlight>

Returns if the journal is currently disabled.

<syntaxhighlight lang="cpp">
void SetJournalDisabled(bool abX);
</syntaxhighlight>

Disables the player's ability to open their journal.

# ''abX'' - True to disable, false to enable again

=== Player ===

<syntaxhighlight lang="c++">
void SetLanternFlickerActive(bool abX);
</syntaxhighlight>

Enables/disables the flicker effect for the lantern's light.

# ''abX'' - True to flicker, false to not flicker

<syntaxhighlight lang="c++">
void SetPlayerInfection(float afInfection);
</syntaxhighlight>

Sets the [[HPL2/AMFP/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 50 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''.

# ''afInfection'' - The level of infection to set

<syntaxhighlight lang="c++">
void AddPlayerInfection(float afInfection);
</syntaxhighlight>

Adds an amount of infection to the player's current amount. This function replaces TDD's ''AddPlayerSanity''.

# ''afInfection'' - 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="cpp">
void GiveInfectionDamage(float afAmount, bool abUseEffect);
</syntaxhighlight>

Increases the infection of the player. This function replaces TDD's ''GiveSanityDamage''.

# ''afAmount'' - Amount of infection damage done
# ''abUseEffect'' - Determines whether a sound effect is played when the infection damage is dealt

<syntaxhighlight lang="c++">
void SetInfectionFauxMode(bool abFauxMode);
</syntaxhighlight>

Enable/disable "faux mode" for infection. In faux mode, the player cannot die of infection and infection sounds don't play.

<syntaxhighlight lang="c++">
void FadePlayerPitchTo(float afX, float afSpeedMul, float afMaxSpeed);
</syntaxhighlight>

Moves the player's pitch (up and down rotation).

# ''afX'' - The target pitch to move towards. 0 = straight forward. Clamped to range: -70 to +70.
# ''afSpeedMul'' - The speed multiplier of the movement. A low value makes a slow change.
# ''afMaxSpeed'' - The max speed of the movement.

<syntaxhighlight lang="c++">
void SetPlayerUsesDragFootsteps(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 ===

==== General ====

<syntaxhighlight lang="c++">
bool GetEntityActive(string& asName);
</syntaxhighlight>

Returns whether an entity in the level is active or not.

# ''asName'' - The entity to check

<syntaxhighlight lang="c++">
void CreateEntityAtArea(string& asEntityName, string& asEntityFile, string& asAreaName, bool abFullGameSave, float afPosX, float afPosY, float afPosZ, float afRotX, float afRotY, float afRotZ);
</syntaxhighlight>

Creates an entity at an area with the specified offsets and rotation. This function replaces TDD's ''CreateEntityAtArea''.

# ''asEntityName'' - The internal name of the created entity
# ''asEntityFile'' - The file for the entity (extension .ent)
# ''asAreaName'' - The area to create entity at
# ''abFullGameSave'' - Determines whether an entity "remembers" its state
# ''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

==== Props ====

<syntaxhighlight lang="c++">
void SetPhysicsAutoDisable(string& asName, bool abAutoDisable);
</syntaxhighlight>

If physics bodies will automatically sleep (become inactive and stop moving). Only used on chandeliers in the campaign.

# ''asName'' - The prop to affect
# ''abAutoDisable'' - Whether physics auto disables or not

<syntaxhighlight lang="c++">
void AttachPropToBone(string& asChildEntityName, string& asParentEntityName, string& asParentBoneName, float fPosX, float fPosY, float fPosZ, float fRotX, float fRotY, float fRotZ);
</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.

# ''asChildEntityName'' - The prop to attach
# ''asParentEntityName'' - The entity that holds the bone to attach to
# ''asParentBoneName'' - The bone within the entity to attach to
# ''afPosX'' - Offset along the X axis
# ''afPosY'' - Offset along the Y axis
# ''afPosZ'' - 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& asChildEntityName);
</syntaxhighlight>

Detaches an attached prop. Note: When detached, physics are not automatically enabled on the prop.

# ''asChildEntityName'' - The attached prop

<syntaxhighlight lang="c++">
void AttachAreaToProp(string& asAreaName, string& asProp, int alBody);
</syntaxhighlight>

Attaches an area to a prop. Originally used to attach a liquid area to a movable water plane entity in the sewers map.

# ''asAreaName'' - The area to attach
# ''asProp'' - The prop to attach area to
# ''alBody'' - The ID of the physics body of the prop to attach to

<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 prop

<syntaxhighlight lang="c++">
void PlayCurrentAnimation(string& asProp, float afFadeTime, bool abLoop);
</syntaxhighlight>

Fades in the active animation, optionally allowing it to loop.

# ''asProp'' - The name of the prop
# ''afFadeTime'' - The fade time between animations
# ''abLoop'' - If the animation should be looped

<syntaxhighlight lang="c++">
void PauseCurrentAnimation(string& asProp, float afFadeTime);
</syntaxhighlight>

Fades out the active animation.

# ''asProp'' - The name of the prop
# ''afFadeTime'' - The fade time between animations

<syntaxhighlight lang="c++">
void SetPropAnimationSpeed(string& asProp, float afSpeed);
</syntaxhighlight>

Set the speed of the animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The prop that is being animated
# ''afSpeed'' - The new animation speed

<syntaxhighlight lang="c++">
void SetPropAnimationPosition(string& asProp, float afPos);
</syntaxhighlight>

Jumps to a specific point in an animation. Generally used in conjunction with ''PlayPropAnimation''.

# ''asProp'' - The prop that is being animated
# ''afPos'' - The time within the animation, in seconds, to jump to

==== Lamps ====

<syntaxhighlight lang="c++">
void SetLampFlickerActive(string& asName, bool abActive);
</syntaxhighlight>

Enables a flickering effect on a Lamp.

# ''asName'' - The lamp entity
# ''abActive'' - Whether to enable flicker

<syntaxhighlight lang="c++">
void FadeLampTo(string& asName, float afR, float afG, float afB, float afA, float afRadius, float afTime);
</syntaxhighlight>

Fades a Lamp'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.

# ''asName'' - The lamp to change
# ''afR'' - Red value (appropriate values are 0 - 10)
# ''afG'' - Green value (appropriate values are 0 - 10)
# ''afB'' - Blue value (appropriate values are 0 - 10)
# ''afA'' - Alpha value (has no effect?)
# ''afRadius'' - The new radius to use (affects illumination strength)
# ''afTime'' - Time in seconds until the light properties have changed

<syntaxhighlight lang="c++">
void SetLampCanBeLitByPlayer(string& asName, bool abX);
</syntaxhighlight>

Enables/disables the player's ability to light a lamp.

# ''asName'' - The name of the Lamp
# ''abX'' - State to set

==== Doors ====

<syntaxhighlight lang="c++">
void SetSwingDoorOpenAmount(string& asName, float afOpenAmount, float afDuration, bool abOpenTowardsMaxAngle);
</syntaxhighlight>

Sets the open amount for a SwingDoor.

# ''asName'' - The SwingDoor entity
# ''afOpenAmount'' - The new amount state to set. Range: 0 - 1
# ''afDuration'' - The time in seconds until the door has changed state
# ''abOpenTowardsMaxAngle'' - If the door will swing to its max angle instead of its min angle

==== Buttons ====

<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOn(string& asName, bool abCanBeSwitchedOn);
</syntaxhighlight>

Changes whether a Button can be switched from off to on.

# ''asName'' - The Button entity
# ''abCanBeSwitchedOn'' - Whether it can be switched on

<syntaxhighlight lang="c++">
void SetButtonCanBeSwitchedOff(string& asName, bool abCanBeSwitchedOff);
</syntaxhighlight>

Changes whether a Button can be switched from on to off.

# ''asName'' - The Button entity
# ''abCanBeSwitchedOff'' - Whether it can be switched off

==== PhoneBoxes ====

<syntaxhighlight lang="c++">
void StartPhoneRinging(string& asName);
</syntaxhighlight>

Enables a PhoneBox to start ringing. A ringing phone box can be interacted with to play some audio files. After interacting, the phone will stop ringing.

# ''asName'' - The PhoneBox entity

<syntaxhighlight lang="c++">
void StopPhoneRinging(string& asName);
</syntaxhighlight>

Stops a ringing PhoneBox.

# ''asName'' - The PhoneBox entity

<syntaxhighlight lang="c++">
void HangUpPhone(string& asName);
</syntaxhighlight>

Hangs up a PhoneBox.

# ''asName'' - The PhoneBox entity

==== Enemies ====

<syntaxhighlight lang="c++">
void AddEnemyPatrolNode(string& asName, string& asNodeName, float afWaitTime, string& asAnimation, bool abLoopAnimation);
</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.

# ''asName'' - The name of the enemy
# ''asNodeName'' - Internal name of path node
# ''afWaitTime'' - The time, in seconds, the enemy waits at this node before continuing. Note: A time of 0 instead randomizes between 1 and 3 seconds, so use 0.01 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.
# ''abLoopAnimation'' - If the animation should be looped

<syntaxhighlight lang="c++">
void SetEnemyMoveType(string& asName, string& asMoveType);
</syntaxhighlight>

Changes how an enemy moves.

# ''asName'' - The name of the enemy
# ''asMoveType'' - The type to change to. Can be "WalkBiped", "RunBiped", "ChargeBiped", "Idle"

<syntaxhighlight lang="c++">
void SetManPigType(string& asName, string& asManPigType);
</syntaxhighlight>

Sets the personality type for a ManPig enemy. Non-functional; left over from an earlier state of development. Only "Freddy" is used as the type, but supposedly it should also accept "Rod" and "Jane".

# ''asName'' - The ManPig enemy.
# ''asManPigType'' - 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"
! Enemy Agent Personality Type !! Primary Behavioral Traits
|-
| Rod ||
*Will maintain a 'safe' distance to the player-character.
*If 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 SetTeslaPigFadeDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should fade the player's view in and out.

#''asName ''- Internal name of the enemy
#''abX''- Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigSoundDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should play the proximity sounds.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void SetTeslaPigEasyEscapeDisabled(string& asName, bool abX);
</syntaxhighlight>

Enables/disables whether a specified Tesla ManPig should be easier to escape from when hunted. If not disabled, easy escape is activated if the player is more than 12.35 meters away, the enemy can't see the player, and the player has less than 75 health. When this occurs, the enemy is forced to stop hunting and wait for half a second.

#''asName'' - Internal name of the enemy
#''abX'' - Enabled/disabled

<syntaxhighlight lang="c">
void ForceTeslaPigSighting(string& asName);
</syntaxhighlight>

Forces a Tesla ManPig to be visible for a short time.

#''asName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
void PlayEnemyAnimation(string& asEnemyName, string& asAnimName, bool abLoop, float afFadeTime);
</syntaxhighlight>

Plays a specific animation for an enemy.

# ''asEnemyName'' - Internal name of the enemy (asterisk is allowed)
# ''asAnimName'' - The name of an animation registered to the enemy
# ''abLoop'' - Whether the animation loops
# ''afFadeTime'' - The fade time between animations

<syntaxhighlight lang="cpp">
void PlayScriptedAnimation(string& asName, string& asAnimationName, bool abLoopAnimation);
</syntaxhighlight>

Plays an animation that has been added to an entity through the Model Editor. Similar to ''PlayEnemyAnimation''.

# ''asName'' - Internal name of the enemy
# ''asAnimationName'' - The animation name
# ''abLoopAnimation'' - Whether to loop the animation or play it only once

<syntaxhighlight lang="c++">
void ChangeEnemyPose(string& asName, string& asPoseType);
</syntaxhighlight>

Changes the pose for an enemy. Can be either "Biped" or "Quadruped".

# ''asName'' - Internal name of the enemy
# ''asPoseType'' - The pose to change to

<syntaxhighlight lang="c++">
void ForceEnemyWaitState(string& asName);
</syntaxhighlight>

Forces the enemy's AI to change its 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.

# ''asName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
void SendEnemyTimeOut(string& asName, float afTimeOut );
</syntaxhighlight>

Forces the enemy's AI to change its state to "TimeOut", which forces the enemy to pause.

# ''asName'' - Internal name of the enemy
# ''afTimeOut'' - The length of the time out

<syntaxhighlight lang="c++">
void StopAnimationAndContinue(string& asName, float afTimeOut);
</syntaxhighlight>

Forces the enemy to stop its patrol animation for the specified amount of time.

# ''asName'' - Internal name of the enemy
# ''afTimeOut'' - The length of the time out

<syntaxhighlight lang="c++">
void SetEnemyBlind(string& asName, bool abX);
</syntaxhighlight>

Sets whether the enemy can see the player if they are within visible range.

# ''asName'' - Internal name of the enemy
# ''abX'' - Whether enemy is blind

<syntaxhighlight lang="c++">
void SetEnemyDeaf(string& asName, bool abX);
</syntaxhighlight>

Sets whether the enemy can hear the player make sound if they are within audible range.

# ''asName'' - Internal name of the enemy
# ''abX'' - Whether enemy is deaf

<syntaxhighlight lang="c++">
bool GetPlayerCanSeeEnemy(string& asEnemyName);
</syntaxhighlight>

Returns whether the enemy is within visible range of the player.

# ''asEnemyName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
float GetEnemyPlayerDistance(string& asEnemyName);
</syntaxhighlight>

Returns the distance (in meters) between the enemy and the player.

# ''asEnemyName'' - Internal name of the enemy

<syntaxhighlight lang="c++">
int GetEnemyState(string& asName);
</syntaxhighlight>

Returns the enemy's current state as an integer.

# ''asName'' - Internal name of the enemy