Frictional Game Wiki

<h1>Areas</h1> <div class="level1"> <p> Areas are oblong-shaped collision zones which can trigger callbacks when the player or other objects enter them; they are also often used as position markers for things spawned in code such as sounds or particle effects. </p> <p> HPL3 ships with several different area types - here's a quick summary of them and of some of their properties. </p> </div> <h2>Trigger</h2> <div class="level2"> <p> The most commonly used type of area, used for all sorts of purposes. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>BlocksLineOfSight</h4> <div class="level4"> <p> If true, this area acts as a blocker for AI seeing the player. </p> </div> <h4>CC_Entities, CC_Funcs</h4> <div class="level4"> <p> Collision callbacks - for example, if you set CC_Entities to <code>player</code> and CC_Funcs to <code>TriggerHitArea</code> then TriggerHitArea will be called in your map script whenever the player enters or leaves the area. </p> </div> <h4>PlayerLookAtCallback</h4> <div class="level4"> <p> Called when the player has the area on-screen. Various other properties in the same section modify exactly when that happens. </p> </div> <h4>PlayerInteractCallback</h4> <div class="level4"> <p> Makes the area interactable, and triggers this callback when the player interacts with it. You can also set <code>CustomInteractIcon</code> etc. </p> </div> <h2>AmbientLight</h2> <div class="level2"> <p> The player, by default, casts a small point light around him so that you can see things even when the room is very dark. This area type changes that ambient light to fit the current area. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>Type</h4> <div class="level4"> <p> Indoors / Outdoors / None </p> </div> <h2>CameraAnimation</h2> <div class="level2"> <p> Used as a camera viewpoint in a camera animation. See <a href="/doku.php?id=hpl3:game:scripting:user_modules:camera_animation" class="wikilink1" title="hpl3:game:scripting:user_modules:camera_animation">Camera Animation</a>. </p> </div> <h2>Climb</h2> <div class="level2"> <p> This area becomes interactable; when you interact, you will climb up to a specified foot position. It's used for things like climbing into vent shafts or climbing up on to a nearby table or something; for higher climbs, you probably want a camera animation or a ladder instead. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>FeetPosition</h4> <div class="level4"> <p> Name of an entity (usually a trigger area) specifying where the feet should land after the climb. </p> </div> <h4>Crouch</h4> <div class="level4"> <p> Specify if the player should be automatically crouched after the climb (useful for vent shafts). </p> </div> <h2>Crawl</h2> <div class="level2"> <p> The player will be crawling on their belly while in this area, and can't run or stand up. Useful for vent shafts. </p> </div> <h2>Datamine</h2> <div class="level2"> <p> The player can interact with this area as if it were a datamine prop - see <a href="/doku.php?id=hpl3:game:scripting:user_modules:datamine" class="wikilink1" title="hpl3:game:scripting:user_modules:datamine">Datamine</a> </p> </div> <h2>DatamineAudioSource, DatamineAnimNode</h2> <div class="level2"> <p> Currently unused. </p> </div> <h2>Description</h2> <div class="level2"> <p> Used with the <a href="/doku.php?id=hpl3:game:scripting:user_modules:description" class="wikilink1" title="hpl3:game:scripting:user_modules:description">Description</a> module. Not used in SOMA. </p> </div> <h2>Distortion</h2> <div class="level2"> <p> This area will apply a <a href="/doku.php?id=hpl3:game:scripting:user_modules:distortion_effects" class="wikilink1" title="hpl3:game:scripting:user_modules:distortion_effects">Distortion Effect</a> to the player while they are in it. </p> </div> <h2>DoorwayTrigger</h2> <div class="level2"> <p> This area is really useful for telling you when the player has walked into a particular part of the map. You set up a doorway with the Z-axis pointing in to the 'inside' and away from the 'outside'. Now when the player walks in through the door, the DoorwayCallback is called with an <code>alState</code> parameter of 1. When the player walks out through the door, the callback is called with an <code>alState</code> of -1. </p> <p> You can also link sets of doorways, which is a great way to figure out if the player is inside an irregular space. If you specify the <code>DoorwayGroup</code> property, then you can use the function <code>Doorway_PlayerIsInGroup</code> to check if the player has crossed into the space delimited by these doorways. (Essentially, if you cross any of the doorways going 'inwards' so <code>alState</code> ==1, then you are in the group; crossing any going 'outwards' so <code>alState</code> ==-1 means you are outside the group). </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>DoorwayEntity</h4> <div class="level4"> <p> This acts just like CC_Entities on an area - it just specifies which entity to check for collisions with. This is usually <code>player</code>. </p> </div> <h4>DoorwayCallback</h4> <div class="level4"> <p> Called when the <code>DoorwayEntity</code> goes in or out of the doorway. </p> </div> <h2>Hide</h2> <div class="level2"> <p> This marks of a specific area as somewhere that the player can hide i.e. they will no longer be visible to AI. This is not used in SOMA, but can work regardless. </p> </div> <h2>InteractAux</h2> <div class="level2"> <p> This is used to expand the interaction area of another entity such as a prop; so that you can, for example, give a small button a bigger interact area. For all purposes, interacting with the area is treated as if you're interacting with the prop itself. If you set interaction disabled on the prop, the area will deactivate too. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>InteractParent</h4> <div class="level4"> <p> The entity to interact with. </p> </div> <h2>Ladder</h2> <div class="level2"> <p> This is used to allow the player to climb ladders. Position the ladder area up the ladder prop. Note that in SOMA rungs have to be 0.5 units apart, and the ladder area itself has to be a multiple of 0.5 units tall and aligned to the rungs for the animation to work properly. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>Exit_Top, Exit_Top_Crouching</h4> <div class="level4"> <p> Use these to specify an area to move to when you step off the top of the ladder (usually a Trigger area). </p> </div> <h4>Exit_Bottom, Exit_Bottom_Crouching</h4> <div class="level4"> <p> Use these to specify an area to move to when you step off the bottom of the ladder (usually a Trigger area). </p> </div> <h2>Liquid</h2> <div class="level2"> <p> Creates an area of liquid - useful for pools of water or for use in SOMA's airlocks. You can control waves, surface colors, fog under water etc. - properties should be reasonably self-explanatory. </p> </div> <h2>MapTransfer</h2> <div class="level2"> <p> Map Transfer areas are used in map transitions; anything within a Map Transfer area is preserved as the next map is loaded. See <a href="/doku.php?id=hpl3:game:map#map_streaming" class="wikilink1" title="hpl3:game:map">Map Streaming</a>. </p> </div> <h2>PathNode</h2> <div class="level2"> <p> Pathnodes are points rather than areas; they are used in AI for the pathfinding system. </p> </div> <h2>PlayerStart</h2> <div class="level2"> <p> Player Start areas are where the player will appear as the result of a map load (by default, the player appears at <code>PlayerStartArea_1</code>, although that can be changed) or as the result of a <code>Player_Teleport()</code> call. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>Crouching</h4> <div class="level4"> <p> Specifies whether the player should be crouching when they appear at that spot. </p> </div> <h2>PosNode</h2> <div class="level2"> <p> Not used in SOMA. </p> </div> <h2>Rope</h2> <div class="level2"> <p> Not used in SOMA. </p> </div> <h2>Sit</h2> <div class="level2"> <p> Sit areas specify an area that the player can interact with to sit down. </p> </div> <h2>Soundscape</h2> <div class="level2"> <p> Soundscape areas are used to set up the ambient sound for particular areas. You'd generally have one soundscape area for every room. See <a href="/doku.php?id=hpl3:game:soundscapearea" class="wikilink1" title="hpl3:game:soundscapearea">Soundscape Area</a> for more details. </p> </div> <h2>Sticky</h2> <div class="level2"> <p> Sticky areas are used to attach other entities to (normally <code>Prop_Grab</code>) - when the entities are pulled away, there'll be resistance, and if you don't pull hard enough they'll snap back. This is used to implement things like pulling power cables from sockets or attaching cables to sockets. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>AttachableBodyName</h4> <div class="level4"> <p> Name or names of bodies that can be attached to this area. Accepts wildcards. </p> </div> <h4>CanDetach</h4> <div class="level4"> <p> If true then the connected body can be detached. </p> </div> <h4>RequiresInteraction</h4> <div class="level4"> <p> If true then bodies will only detach or attach if the player is actually interacting with them (as opposed to e.g. walking into an object to knock it free). </p> </div> <h4>MoveBody, RotateBody</h4> <div class="level4"> <p> Whether to orient the body to the attach position. </p> </div> <h4>AttachFunction</h4> <div class="level4"> <p> Called when an entity is attached to this area. </p> </div> <h4>DetachFunction</h4> <div class="level4"> <p> Called when an entity is detached from this area. </p> </div> <h4>SpringyActive, SpringyForceMul, SpringyDetachTime</h4> <div class="level4"> <p> Use these to give some resistance to the detachment or attachment - so that the attach area 'sucks in' the body. </p> </div> <h2>Tool</h2> <div class="level2"> <p> If the player walks into a tool area and has the specified tool in their inventory, then it will automatically be equipped (i.e. brought out and shown on screen in their hands). This is what is used for showing the Omnitool next to an airlock control panel. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>ToolsToEquip</h4> <div class="level4"> <p> A list of tools to bring out when in this area. </p> </div> <h4>ConnectedToolAreas</h4> <div class="level4"> <p> Other tool areas that are part of the same group; this is to make it easy to set up irregularly shaped tool areas by combining multiple rectangular areas. </p> </div> <h4>LookEntities</h4> <div class="level4"> <p> Specify a look entity, and the tool will only be brought out if the player is facing that entity. In most cases, it would be the object that they can interact with e.g. the airlock panel. This is used so that the tool isn't brought out if the player backs in to a tool area. </p> </div> <h2>AgentRepel</h2> <div class="level2"> <p> This area type repels AI creatures who enter it. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>ExitArea</h4> <div class="level4"> <p> Specifies a particular point (usually a TriggerArea) to head towards if the agent enters this area. </p> </div> <h2>VisibilityArea</h2> <div class="level2"> <p> The visibility area is used to divide a map into areas that should not be visible at the same time. This helps the engine cull objects that are outside of the view and should not be visible. Adding viability areas to the map will increase performance since it will give the engine an easier time partitioning the objects. It is also possible to manually disable a visibility area, this will hide all the objects that are inside it. An object will be part of all visibility areas that it is fully inside of. </p> <p> Objects that doesn't fit inside any of the placed areas will get added to a main render container that has an infinite size. </p> </div> <h3>Placement</h3> <div class="level3"> <p> Visibility areas should be placed around large rooms, floors or large outdoor zones. They should be placed so that when you are inside one of the areas the other areas are not visible because it is occluded by geometry (like floors or walls). If a map has multiple floors with stairways between them then it would be a good idea to place one area per floor. </p> <p> A visibility area should be added to rooms that have a lot of objects. If the room is big but has few objects then placing an area is not needed. Most visibility areas should be large, covering a whole floor, but some can be small if the room has a lot of expensive objects. Only objects that are fully inside an area will be added to it. </p> </div> <h3>Add Partial Intersecting Objects</h3> <div class="level3"> <p> If objects that are only partially intersecting the area should be added to it. The default behavior is that only objects that are fully inside the area will be added. Enabling this can lead to false positives and the objects being culled when they should be visible. </p> </div> <h3>Min Objects Per Node</h3> <div class="level3"> <p> Small nodes will merge into larger ones if the number of objects per node is less than this value. This is based on the average and not enforced per node. </p> </div> <h3>Max Objects Per Node</h3> <div class="level3"> <p> Large nodes will be split into smaller ones if the number of objects per node is larger than this value. </p> </div> <h3>Scripting</h3> <div class="level3"> <p> <b>Visibility_SetAreaActive(const tString &in asName, bool abActive)</b> </p> <p> Disable or enable an area and make all objects inside invisible. </p> <p> <b>Visibility_SetMainActive(bool abActive)</b> </p> <p> Disable or enable the main area and make all objects that are not part of a visibility area invisible. This can cause issues with large lights being disabled. Add Partial Intersecting Objects can be used with this to disable world the outside while inside a room. </p> <p> <b>Visibility_SetTerrainActive(bool abActive)</b> </p> <p> Hides terrain. </p> </div> <h3>Notes</h3> <div class="level3"> <p> Visibility areas can be rotated to get a better fit. Rotating an area makes updating of dynamic objects a little more expensive. </p> <p> Play around with min/max objects per node to get the best result (F5 is supported). The goal is to reduce the number of draw calls and queries with draw calls being the main stat. </p> <p> Placing visibility areas will never make objects on the map disapear when they should be in view. </p> </div> <h2>Visibility Portal</h2> <div class="level2"> <p> A visibility portal is an area used to link together two or more visibility areas. A visibility area that is connected to a portal will only be visible if the portal is visible or if the camera is inside it. If the camera is inside of a visibility area then all the portals connected to it will be used as a portal to the outside. </p> <p> A visibility portal will also clip the view frustum. This means that only objects that can be seen through the portal will be visible. Frustum clipping can also be used to disable other portals so that areas can be skipped directly. </p> <p> <a href="/doku.php?id=hpl3:game:portals.png&1791x396}}" class="wikilink2" title="hpl3:game:portals.png" rel="nofollow">portals.png</a> </p> <p> The left image shows how a portal is used to cull the outside world. The middle image show one visibility area connected to two others with the use of portals, only the objects inside of the clipped frustum will get rendered. The last image shows that portals can be used to clip other portals. The current setup is limited so that only the first portal is used to cull other portals. If you look at the right most portal you can see that the whole portal is being used instead of clipping it with the portal before it, this might get fixed later. </p> <p> Portals can also be combined with occlusion query based culling. This means that the GPU can check if a portal is blocked behind other rendered objects, and if that happens then the portal gets closed. </p> <p> Portals should always be intersecting with all the visibility areas that it belongs too. If it is placed outside then the whole visibility area might get culled when it should be visible. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>Connected Areas</h4> <div class="level4"> <p> List all the areas that are connected to this portal. Separate using ; </p> </div> <h3>Notes</h3> <div class="level3"> <p> A good place to place portals are windows and doors. The portal should always be a little bigger than the window or door that it covers. If it is smaller then there might be objects that pop into view. </p> <p> Portals can be used on outdoor levels as well. If there is no roof on the level then the portal should be scaled to a height that covers the whole wall. </p> <p> Portals also work when retrieving shadow casters. </p> <p> Be vary of how many portals and areas that you use on a map. Since one query is used per visible portal you might end up having more draw calls than you would without the portal. </p> <p> Portals can be disabled in the debug menu. </p> <p> Unlike visibility areas, adding portals incorrectly will make objects pop in and out when they should be visible. </p> </div> <h2>Zoom</h2> <div class="level2"> <p> See also <a href="/doku.php?id=hpl3:game:readables" class="wikilink1" title="hpl3:game:readables">Readables</a>. </p> <p> A zoom area shows a magnifying glass icon when the player interacts with it; when they interact, the player's viewpoint is moved in towards the area, so that they're focused on the contents. You can also add optional text or GUI to pop up over the area. </p> <p> This is used in SOMA for things like whiteboards, maps and pictures on the wall. </p> </div> <h3>Important Properties</h3> <div class="level3"> </div> <h4>TextCategory, TextEntry</h4> <div class="level4"> <p> Specify the text to appear when you click interact for a second time. This is used for simple descriptive text. </p> </div> <h4>OnGuiFunction</h4> <div class="level4"> <p> Instead of text appearing, if you specify an OnGuiFunction that will be called instead. This is useful for drawing more complex text layouts such as the key locations on a map. </p> </div>