This page is here as a reference documentation available online covering the main script functions within HPL3. The Basic Code section contains scripts that are available by default and found within the hps_api.hps file located in the SOMA game directory. Under “Helper Files” you will find the functions referenced in the specific helper files which require a script import from the script folder.

Note: This is a work-in-progress page. In time, it will contain much more, including all built-in functions, helper files and possibly more.

The code referenced here is included by default in the game, and can be accessed without the use of a #include statement, contrary to the helper scripts. Each function is followed by a short description, argument explanations and callback syntax (if used).

#include <helper.hps>

Used to include scripts and referencing from various helper files created outside of the Base Scripts. (Eventually) All the helper files as found in SOMA/script/helpers/ will be included below the main scripts.

class cScrMap : iScrMap { }

A declaration of a class where the map (cScrMap) is able to access functions and reference material from scripts (iScrMap). Your code for your map should go within the braces of this declaration.

void Setup(){ }

Used when the map is being loaded/prepared/set up for the player. Called before OnStart();. Useful for setting up variables in the level.

void OnStart(){ }

Called when the player first enters the map, and only on this first occasion. Useful for setting up callbacks.

void OnEnter(){ }

Called when the player enters and re-enters the map. Useful for setting up variables and “hub” levels (“hub” meaning, levels that branch off into others).

void OnLeave(){ }

Called when the player exits the level. Useful for ending certain events which occurred in the previous level (Using Music_Stop() for example).

void OnAction(){ }

Called when an action is completed. Often used by Frictional Games to debug and test certain events.

Other callbacks which can be used to perform certain actions can be found here.

void Billboard_SetVisible(const tString &in asBillboardName,  bool abVisible);

Sets whether a billboard should be rendered or not.

asBillboardName - name of the billboard. Wildcards * supported.
abVisible - true = visible, false = invisible.

void Body_AddForce(const tString &in asBodyName,  const cVector3f &in avForce,  bool abLocalSpace);

Adds push force to a body.

asBodyName - the name of the body.
avForce - the push force to apply.
abLocalSpace - true = local force, false = global force.

void Button_SetSwitchedOn(const tString& in asName,  bool abState,  bool abEffects);

Switches a button on or off.

asName - name of the button.
abState - true = on, false = off.
abEffects - whether the change should use effects associated with it. If false, the player will not be apparent to the change.

void EnergySource_SetEnergy(const tString &in asName,  float afX);

Sets the energy level of an energy source.

asName - name of the energy source.
afX - the energy amount.

bool Entity_Exists(const tString &in asName);
bool Entity_Exists(tID aID);

Check if an entity exists in the level. Returns true if found.

asName - the name of the entity to search for.
OR
aID - the ID of the entity to search for.

bool Entity_SetActive(const tString &in asName, bool abActive);

Set whether an entity is active (visible and functioning) or not.

asName - the name of the entity (wildcards * are supported).
abActive - if active or not.

bool Entity_IsActive(const tString &in asName);

Check if an entity is active (visible and functioning) or not.

asName - the name of the entity (wildcards * are supported).

void Entity_SetInteractionDisabled(const tString &in asEntityName,  bool abX);

Sets whether an entity can be interacted with by the player or not.

asEntityName - the name of the entity (wildcards * are supported).
abX - true = interaction disabled | false = interaction enabled.

void Entity_SetMaxInteractionDistance(const tString &in asEntityName,  float afDistance);

Override the default max distance an entity can be interacted with.

asEntityName - the name of the entity (wildcards * are supported).
afDistance - the distance (in meters) the entity can be interacted with from.

bool Entity_IsInteractedWith(const tString &in asName);

Checks whether an entity is being interacted with.

asName - the name of the entity.

void Entity_Sleep(const tString &in asName);

Forces the entity to sleep. This disables Update and PostUpdate. Has no effect if entity is already sleeping.

asName - the name of the entity (wildcards * are supported).

void Entity_WakeUp(const tString &in asName);

Wakes a sleeping entity. This enabled Update and PostUpdate. Has no effect if entity is already awake.

asName - the name of the entity (wildcards * are supported).

bool Entity_IsSleeping(const tString &in asName);

Checks whether an entity is asleep.

asName - the name of the entity.

void Entity_SetAutoSleep(const tString &in asName,  bool abX);

Sets whether an entity should automatically sleep when it doesn't require updates.

asName - the name of the entity (wildcards * are supported).
abX - enabled or disabled.

bool Entity_GetAutoSleep(const tString &in asName);

Gets whether an entity automatically goes to sleep when it doesn't require updates.

asName - the name of the entity.

void Entity_SetIsOccluder(const tString &in asName,  bool abOccluder);

Set whether an entity is an occluder.

asName - the name of the entity (wildcards * are supported).
abOccluder - enabled or disabled.

bool Entity_IsOccluder(const tString &in asName);

Checks whether an entity is an occluder.

asName - the name of the entity.

void Entity_SetVarString(const tString&in asEntityName, const tString&in asVarName, const tString&in asX);
void Entity_SetVarBool(const tString&in asEntityName, const tString&in asVarName, bool abX);
void Entity_SetVarInt(const tString&in asEntityName, const tString&in asVarName, int alX);
void Entity_SetVarFloat(const tString&in asEntityName, const tString&in asVarName, bool afX);
void Entity_SetVarVector2f(const tString&in asEntityName, const tString&in asVarName, const cVector2f&in avX);
void Entity_SetVarVector3f(const tString&in asEntityName, const tString&in asVarName, const cVector3f&in avX);
void Entity_SetVarColor(const tString&in asEntityName, const tString&in asVarName, const cColor&in aX);

Sets a value of an entity variable.

asName - the name of the entity (wildcards * are supported).
asVarName - the name of the variable for the entity.
aX - the value of the variable.

void Entity_IncVarInt(const tString&in asEntityName,  const tString&in asVarName,  int alX);
void Entity_IncVarFloat(const tString&in asEntityName,  const tString&in asVarName,  float afX);
void Entity_IncVarVector2f(const tString&in asEntityName,  const tString&in asVarName,  const cVector2f&in avX);
void Entity_IncVarVector3f(const tString&in asEntityName,  const tString&in asVarName,  const cVector3f&in avX);

Increments a value of an entity variable.

asName - the name of the entity (wildcards * are supported).
asVarName - the name of the variable for the entity.
aX - the value to add.

tString Entity_GetVarString(const tString&in asEntityName,  const tString&in asVarName);
bool Entity_GetVarBool(const tString&in asEntityName,  const tString&in asVarName);
int Entity_GetVarInt(const tString&in asEntityName,  const tString&in asVarName);
float Entity_GetVarFloat(const tString&in asEntityName,  const tString&in asVarName);
cVector2f Entity_GetVarVector2f(const tString&in asEntityName,  const tString&in asVarName);
cVector3f Entity_GetVarVector3f(const tString&in asEntityName,  const tString&in asVarName);
cColor Entity_GetVarColor(const tString&in asEntityName,  const tString&in asVarName);

Gets the value of an entity variable.

asName - the name of the entity.
asVarName - the name of the variable for the entity.

bool Entity_AddCollideCallback(const tString &in asParentName,  const tString &in asChildName,  const tString &in asFunction);

Adds a callback between two entities (objects, areas, player etc) when they collide with each other. Collisions include when “uncolliding” as well. Wildcards * are supported in names.

asParentName - the first entity (for player collisions, this is always the player)
asChildName - the second entity to check against.
asFunction - name of the callback function for when these objects collide.

Callback syntax:
FunctionName(const tString &in asParent, const tString &in asChild, int alState)
alState - 1 = colliding, -1 = uncolliding, 0 = both.

Returns a boolean of whether the callback is repeated upon completetion. If true, callback can be called again. If false, callback is removed.
Abbreviation syntax for the callback function code snippet: clbCollide

bool Entity_RemoveCollideCallback(const tString &in asParentName,  const tString &in asChildName);

Removes a callback for entity collisions. Wildcards * supported in names.

asParentName - the first entity (for player collisions, this is always player)
asChildName - the second entity.

bool Entity_GetCollide(const tString &in asEntityA,  const tString &in asEntityB);

Check whether two entities are already colliding. Wildcards * are NOT supported.

asEntityA - the first entity.
asEntityB - the second entity.

Returns true if colliding, else false.

void Entity_SetCollideCharacter(const tString &in asEntityName,  bool abActive);

Enable/disable an entity's collision with a character for all bodies in the entity.

asEntityName - the name of the entity. Wildcards * are supported.
abActive - true = collision on, false = collision off.

void Entity_SetCollide(const tString &in asEntityName,  bool abActive);

Enable/disable an entity's collision for all bodies in the entity.

asEntityName - the name of the entity. Wildcards * are supported.
abActive - true = collision on, false = collision off.

void Entity_SetEffectsActive(const tString &in asEntityName,  bool abActive,  bool abFadeAndPlaySounds);

Enables/disables whether an entity uses effects.

asEntityName - name of the entity/prop. Wildcards * are supported.
abActive - true = activates effects, false = deactivates effects.
abFadeAndPlaySounds - if effects should fade in/out and play sounds.

void Entity_SetReflectionVisibility(const tString &in asEntityName,  bool abVisibleInReflection,  bool abVisibleInWorld);

Sets whether an entity is drawn in reflections or not, and/or in the real world or not.

asEntityName - the name of the entity. Wildcards * are supported.
abVisibleInReflection - whether the entity is drawn in reflections.
abVisibleInWorld - whether the entity is drawn in the real world.

void Entity_SetEffectBaseColor(const tString &in asEntityName, const cColor&in aColor);

Sets the base color for the entity's effects.

asEntityName - the name of the entity. Wildcards * are supported.
aColor - the color all effects will be multiplied with.

void Entity_FadeEffectBaseColor(const tString &in asEntityName, const cColor&in aColor,  float afTime);

Fades the base color for the entity's effects.

asEntityName - the name of the entity. Wildcards * are supported.
aColor - the color all effects will be faded to.
afTime - the time in seconds the fade takes to finish.

void Entity_SetColorMul(const tString &in asEntityName,  const cColor&in aColor);

Sets the color multiplier of the entity.

asEntityName - the name of the entity. Wildcards * are supported.
aColor - the color to set the multiplier to.

void Entity_AddForce(const tString &in asEntityName,  const cVector3f &in avForce,  bool abLocalSpace,  bool abOnlyMainBody);

Adds a push force to the entity.

asEntityName - the name of the entity. Wildcards * are supported.
avForce - the force to add.
abLocalSpace - true = local force is added relative to the rotation of the entity, false = global force is added in a world space
abOnlyMainBody - true = force is added only to the main body of the entity, false = force is added to all bodies of the entity.

void Entity_AddForceFromEntity(const tString &in asEntityName,  const tString &in asForceEntityName,  float afForce,  bool abOnlyMainBody);

Adds a push force to the entity away from another entity.

asEntityName - the name of the entity. Wildcards * are supported.
asForceEntityName - the name of the entity to push away from.
afForce - magnitude of the force. Negative values attract the entity to the force entity.

void FogArea_SetVisible(const tString &in asFogAreaName,  bool abActive);

Sets whether a fog area is visible or not.

asFogAreaName - name of the fog area.
abActive - true = active, false = inactive.

void Grab_SetForceMul(const tString& in asName,  float afForceMul);

Sets the force multiplier of a grab prop.

asName - name of the grab prop.
afForceMul - the new multiplier.

void IrradianceSet_FadeIn(const tString &in asSet,  float afTime);

Fades in the specified set on all probes belonging to it. This also fades out the currently active set for these probes.

asSet - the set to fade in.
afTime - how long it should take until the fade is done.

bool Joint_IsBroken(const tString &in asJointName);

Checks whether the specified joint is broken.

asJointName - the name of the joint.

void Lamp_SetLit(const tString& in asName,  bool abLit,  bool abEffects);

Sets the lit state of a lamp.

asName - name of the lamp.
abLit - true = lamp is lit, false = lamp is unlit.
abEffects - whether the change should use effects associated with it. If false, the change will not be apparent to the player.

void LensFlare_SetVisible(const tString &in asLensFlareName,  bool abVisible);

Sets if a lens flare should be rendered or not.

asLensFlareName - name of lens flare. Wildcards * supported.
abVisible - true = visible, false = invisible.

void LevelDoor_SetLocked(const tString& in asName,  bool abState);

Sets a LevelDoor to be locked or unlocked.

asName - name of the level door.
abState - true = locked, false = unlocked.

int Lever_GetState(const tString& in asName);

Gets the state of a lever.

asName - name of the lever.

Returns -1 for minimum, 0 for middle, 1 for maximum state.

void Light_FadeTo(const tString &in asLightName,  const cColor &in acColor,  float afRadius,  float afTime);

Fades one or more light objects to a specified color and radius.

asLightName - name of the light(s). Wildcards * supported.
acColor - the color to fade to.
afRadius - the radius to fade to. If lower than 0, the current radius is used.
afTime - how long it should take until the fade is done.

bool Map_GetParticleSystemArray(const tString &in asName,  array<cParticleSystem@> &inout avOutParticles);

Creates an array of particle systems with a given name.

asName - name of particle systems. Wildcards * supported.
avOutParticles - reference to array that will be filled with particle systems.

void Material_Preload(const tString &in asFile);

Preloads a material

asFile - the .mat material file to preload.

void Meter_SetState(const tString& in asName,  float afState,  bool abFadeToState = true);

Sets the state of the needle object in a meter, which then makes the needle move to the specified state.

asName - name of meter object.
afState - percentage of where the needle should be. 0-1 (minimum position - maximum position). abFadeToState - if true, then the needle will fade to the state instead of skipping to it.

void MoveObject_SetState(const tString& in asName,  float afState);

Sets the state of a move object. This makes it move to a certain position between its minimum and maximum position (or beyond if set to <0 or >1).

asName - name of the move object.
afState - the state to set the move object to at speeds defined in the entity file.

void MovingButton_SetSwitchedOn(const tString& in asName,  bool abState,  bool abEffects);

Switches a MovingButton on or off.

asName - name of the button.
abState - true = on, false = off.
abEffects - whether the change should use effects associated with it. If false, the player will not be apparent to the change.

cParticleSystem@ ParticleSystem_CreateAtEntity(const tString &in asPSName,  const tString &in asPSFile,  const tString &in asEntity,  bool abAttach);

Create a particle system at an entity or area.

asPSName - name of the particle system to be created.
asPSFile - the .ps file to create the particle system from.
asEntity - the entity to create the particle system at. Can be “Player”.
abAttach - whether the particle system should attach to the entity it is created at.

Returns: The created particle system, or null if the function fails.

bool PhysicsSlideDoor_GetClosed(const tString& in asName);

Returns true if the door is closed, else false.

asName - name of the door.

void Prop_SetHealth(const tString &in asPropName,  float afHealth);

Sets the health of a prop. Can be used to destroy objects.

asPropName - name of the prop. Wildcards * supported.
afHealth - the health to set.

void Readable_SetCloseCallback(const tString &in asName,  const tString &in asCallback);

Sets the close callback of a readable prop.

asName - name of the readable prop.
asCallback - name of the callback function.

Callback syntax: void Function(const tString &in asEntity)

void Slide_SetSlideAmount(const tString& in asName,  float afAmount);

Sets the slide amount of a Slide prop, 0 being its minimum position and 1 being its maximum.

asName - name of the prop.
afAmount - the slide amount.

void SlideDoor_SetClosed(const tString& in asName,  bool abClosed,  bool abInstant = false);

Sets the close state of a SlideDoor. Simplified version of SlideDoor_SetOpenAmount.

asName - name of the door.
abClosed - true = close, false = open.
abInstant (optional) - whether the door should slide to the correct state or just have the new position set instantly.

void SwingDoor_SetOpenAmount(const tString& in asName,  float afOpenAmount);

Sets a swing door to a specific open state instantly.

asName - name of the prop. Wildcards * supported.
afOpenAmount - 0 = closed, 1 = completely open. 0.5f = half state.

void Terminal_SetAllowInteraction(const tString& in asName,  bool abX);

Sets whether the terminal should allow interactions from the player.

asName - name of the terminal. Wildcards * are supported.
abX - true = allowed, false = denied.

void Tool_SetAutoHideAfterPickup(const tString &in asName,  bool abX);

Sets if a tool should be hidden automatically after getting picked up and being displayed for a brief moment.

asName - name of the tool.
abX - true = hide automatically, false = do not hide.

int Wheel_GetState(const tString& in asName);

Gets the state of a wheel.

asName - name of the wheel.

Returns -1 for minimum, 0 for middle, 1 for maximum state.

Helper files are seperate .hps files which contain many further functions and codes which are of use to the developer. The following are grouped by their helper file name. In order to use these, you need to specify with an #include <helper.hps> at the top of your code, which is done automatically when you save your map for the first time. These codes are found in SOMA/script/helpers/ , and are grouped on this page under which one you require. To search this, from most browsers, you can press Ctrl+F and start typing in a term.

The following codes require #include “helpers/helper_ai.hps”.

void Agent_FaceEntity(const tString &in asAgentName, const tString &in asLookAtTarget);

Instantly sets the yaw of the agent to make it look at the specified entity.

asAgentName - Name of the agent. Wildcard (*) supported.
asLootAtTarget - Name of entity to look at.

bool Agent_PlayerDetected(const tString &in asAgentName);

Gets if the player has been detected by an agent. Returns true if so.

asAgentName - Name of the agent. Wildcard (*) supported.

void Agent_RevealPlayerPosition(const tString &in asAgentName, bool bForceRedetect=false);

Reveals the player's current position to the agent.

asAgentName - name of the agent. Wildcard (*) supported.

void Agent_SetAutoDisableCallback(const tString &in asAgentName, const tString &in asCallbackFunc);

Sets the function that is called when the disabling made by Agent_SetAutoDisableWhenOutOfSightActive(); happens

asAgentName - name of the agent. Wildcard (*) supported.
asCallbackFunc - Function called when the disabling happens.
Callback syntax: void MyFunc(const tString&in asEntityName)

void Agent_SetAutoDisableWhenOutOfSightActive(const tString &in asAgentName, bool abActive, float afMinDistance);

When active, the agent will be a disabled (SetActive(false)) when a certain distance away from the player and no longer seen.

asAgentName - name of the agent.Wildcard (*) supported.
abActive - if the disabling is active (should be disabled = true)
afMinDistance - The minimum distance from the player for this to happen.

void Agent_SetSensesActive(const tString &in asAgentName, bool abX);

Set if the agent should have its senses (hearing/vision/etc) enabled.

asAgentName - name of the agent. Wildcard (*) supported.
abX - If the senses should be active.

void Agent_SetStaticCollider(const tString &in asAgentName, bool abX);

Set if the agent will collide with the environment (objects and stuff will still collide with it!)

asAgentName - name of the agent. Wildcard (*) supported.
abX - If the character should be static and NOT move about.

void Agent_SetViewRangeMul(const tString &in asAgentName, float afRangeMul);

Sets the view range multiplier of the specified agent

asAgentName - name of the agent. Wildcard (*) supported.
afRangeMul - the range multiplier to set.

void Agent_TeleportFeetToEntity(const tString &in asAgentName, const tString &in asTargetName);

Teleport the agent's foot position to a specific other entity.

asAgentName - name of the entity to teleport.
asTargetName - name of the entity to teleport to.

void BarkMachine_SetActive(const tString&in asEntityName, bool abActive);

Sets if the barkmachine is active (this will only affect random sounds)

asEntityName - name of the entity with the barkmachine.
abActive - if active or not.

void BarkMachine_PlayVoice(const tString&in asEntityName, const tString&in asSubject, int alPrio, float afMinDistance=-1, float afMaxDistance=-1, float afMaxPlayerListeningRange=-1);

Plays a voice from the barkmachine tied to the entity.

asEntityName - name of the entity with the barkmachine.
asSubject - the name of the voice subject.
alPrio - the prio of the voice, if there is already one playing in the same scene prio must be higher for this to play.
afMinDistance - The distance where volume starts getting quiet. If below 0, default is used.
afMaxDistance - The maximum hearing range. If below 0, default is used.
afMaxPlayerListeningRange - The maximum that subtitles are displayed. If below 0, default is used.

void HeadTracker_SetActive(const tString&in asEntityName, bool abX);

Turns on and off head tracking.

asEntityName - name of the entity with the HeadTracker.
abX - if headtracking is enabled or not

bool HeadTracker_IsActive(const tString&in asEntityName);

If head tracking is active or not.

asEntityName - name of the entity with the HeadTracker.

void HeadTracker_SetAngleOffset(const tString&in asEntityName, float afX);

Sets the offset of the headtracker angle. Useful if the character is not facing in the direction of the meshentity forward vector.

asEntityName - name of the entity with the HeadTracker.
afX - The angle offset, in degrees.

void HeadTracker_SetTargetEntity(const tString&in asEntityName, const tString&in asTargetEntityName);

Sets the target of the head tracking.

asEntityName - name of the entity with the HeadTracker.
asTargetEntityName - The target of the tracking.

void NPC_SetVoiceName(const tString &in asNpcName, const tString &in asVoiceName);

Sets the voice name for an NPC. This also automatically sets the source of the voice as the npc.

asNpcName - name of the NPC.
asVoiceName - name of the voice as defined in the voicehandler file.

bool NPC_IsTalking(const tString &in asNpcName);

Checks if the NPC is being talked to.

asNpcName - name of the NPC.

void NPC_SetCanBeTalkedTo(const tString &in asNpcName, bool abX);

Sets if the NPC can be talked to (interacted with)

asNpcName - name of the NPC. Wildcard (*) supported.
abX - if can be talked to.

void NPC_SetMainAnimation(const tString &in asNpcName, const tString& in asAnim, bool abPlayTransition = true, const tString &in asCallbackFunc="", float afFadeTime=0.5, bool abGlobalSpace=false);

Sets if the NPC can be talked to (interacted with)

asNpcName - name of the NPC. Wildcard (*) supported.
asAnim - The name of the animation.
abPlayTransition - If a transition animation should be played.
asCallbackFunc - name of callback function. Only used if there is a transition animation.
afFadeTime - time it takes to fade to the animation.
abGlobalSpace - if the animation takes place in global space
Callback syntax: void Func(const tString &in asEntityName, const tString &in asAnimName)

void NPC_PlayExtraAnimation(const tString &in asNpcName, const tString& in asAnim, float afFadeTime=0.3, const tString &in asCallbackFunc="", bool abGlobalSpace=false);

Plays an extra animation for the NPC. Will return to main animation (see NPC_SetMainAnimation) when done.

asNpcName - name of the NPC. Wildcard (*) supported.
asAnim - The name of the animation.
afFadeTime - The time it takes to fade in the animation.
asCallbackFunc - name of callback function.
Callback syntax: void Func(tString &in asEntityName, tString &in asAnimName)

void NPC_StopAllAnimations(const tString &in asNpcName, float afFadeTime=0.0f);

Stops all animations for the NPC.

asNpcName - name of the NPC. Wildcard (*) supported.
afFadeTime - The time it takes to fade out.

void NPC_PlayEmotion(const tString &in asNpcName, const tString& in asEmotion, float afDuration, float afWeight = 1.0f, float afFadeTime = 0.25f);

Stops all animations for the NPC.

asNpcName - name of the NPC. Wildcard (*) supported.
asEmotion - name of the emotion, “Smile/Sad/Happy/Surprised/Wink/Wondering/Angry/Worried/Scared”
afDuration - how long the emotion should be active
afWeight - how strong the emotion should be
afFadeTime - fade in and out time for the emotion

void NPC_MoveToNode(const tString &in asNpcName, const tString& in asNodeName, const tString& in asCallbackFunc);

Moves the NPC to a path node.

asNpcName - name of the NPC. Wildcard (*) supported.
asNodeName - The name of the path node.
asCallbackFunc - The name of callback called when end is reach.
Callback syntax: void Func(const tString& in asEntityName, bool abReachedEnd)

void Critter_SetGroupEntity(const tString &in asCritter, const tString &in asGroupEntity);

Sets the entity the critter should flock around

asCritter - name of the Critter. Wildcard supported.
asGroupEntity - The name of the group entity.

void Critter_AddExtraEscapeEntity(const tString &in asCritter, const tString &in asEscapeEntity);

Adds an entity that the critter should try to avoid the same way it does with the player.

asCritter - name of the Critter. Wildcard (*) supported.
asEscapeEntity - The name of the entity to escape from.