Frictional Wiki - User contributions [en]

HPL3/SOMA/Entities/Working with Physics Bodies

2026-10-02T17:34:36Z

TiMan: Redirect SOMA entity documentation path to the shared HPL3 physics-body workflow

#REDIRECT [[HPL3/Entities/Working with Physics Bodies]]

HPL3/SOMA/Entities/Entity Notes

2026-10-02T17:34:35Z

TiMan: Move preserved and expanded Entity Notes guidance to the shared HPL3 article

#REDIRECT [[HPL3/Entities/Entity Notes]]

HPL3/SOMA/Entities/Model Editor Preferences

2026-10-02T17:34:33Z

TiMan: Redirect SOMA entity documentation path to the shared HPL3 Model Editor preferences guide

#REDIRECT [[HPL3/Entities/Model Editor Preferences]]

HPL3/SOMA/Entities/Model Editor Controls

2026-10-02T17:34:32Z

TiMan: Redirect SOMA entity documentation path to the shared HPL3 Model Editor controls guide

#REDIRECT [[HPL3/Entities/Model Editor Controls]]

HPL3/Entities/Working with Physics Bodies

2026-10-02T17:34:22Z

TiMan: Create shared HPL3 physics-body workflow from installed editor labels and shipped SOMA, Rebirth, and Bunker entity data

A '''physics body''' groups one or more collision shapes and gives them shared physical, collision, and surface settings. The Model Editors and shipped entities for SOMA, Amnesia: Rebirth, and Amnesia: The Bunker use the same core body structure.

== Bodies, shapes, and children ==

Collision geometry is stored as shapes. The common shape types are '''Box''', '''Cylinder''', '''Sphere''', and '''Capsule'''. A body references its member shapes by ID; it can also reference child objects such as submeshes.

For example, this shortened structure contains one box shape, one attached child, and one body:

<syntaxhighlight lang="xml">
<Shapes>
<Shape ID="1" Name="Shape_1" ShapeType="Box" ... />
</Shapes>
<Bodies>
<Body ID="2" Name="Body_1" Mass="0" Material="Default" ...>
<Children>
<Child ID="0" />
</Children>
<Shape ID="1" />
</Body>
</Bodies>
</syntaxhighlight>

The body and shape transforms are stored independently. Use the editor rather than manually changing IDs: joints, attachments, and other entity data can refer to those IDs.

== Creating a body ==

# Create and position one or more collision shapes around the model.
# Select the shape or shapes that should behave as one unit.
# Press '''Create Body'''. Multiple selected shapes produce one body containing multiple shape references.
# Select the new body and give it a clear, unique name.
# Set its material, mass, damping, speed limits, and collision flags.
# Attach only the meshes, bones, lights, sounds, particle systems, or other supported components that should follow that body.
# Save the entity and inspect the result in Entity Preview and in a small test map.

'''Detach from Body''' removes a selected shape from its body. It does not delete the shape. If the shape should be part of a different body, detach it and then create or assign the intended grouping in the editor.

== Core body properties ==

The following properties are serialized by shipped entities in all three games:

{| class="wikitable"
! Editor property !! Stored attribute !! Role
|-
| Body Material || <code>Material</code> || Selects the physics/surface material name.
|-
| Mass || <code>Mass</code> || Sets the body's mass value. Shipped entities use both zero and positive values; choose a value appropriate to the entity type and intended motion.
|-
| Angular Damping / Linear Damping || <code>AngularDamping</code> / <code>LinearDamping</code> || Reduce rotational and translational motion over time.
|-
| Max Angular Speed / Max Linear Speed || <code>MaxAngularSpeed</code> / <code>MaxLinearSpeed</code> || Limit rotational and translational speed.
|-
| Buoyancy density mul || <code>BuoyancyDensityMul</code> || Multiplies the body's buoyancy-density value.
|-
| Blocks sound / Blocks light || <code>BlocksSound</code> / <code>BlocksLight</code> || Control whether the body participates in sound or light blocking.
|-
| Continuous collision || <code>ContinuousCollision</code> || Enables continuous-collision handling for the body.
|-
| Can attach character / Pushed by character gravity || <code>CanAttachCharacter</code> / <code>PushedByCharacterGravity</code> || Control character interaction with the body.
|-
| Collide character / Collide non character || <code>CollideCharacter</code> / <code>CollideNonCharacter</code> || Select the broad collision groups the body responds to.
|-
| Volatile || <code>Volatile</code> || Marks the body with the engine's volatile-body flag.
|-
| Use surface effects || <code>UseSurfaceEffects</code> || Enables effects associated with the selected surface material.
|-
| Has gravity || <code>HasGravity</code> || Controls whether gravity is applied.
|}

Amnesia: Rebirth entities may additionally serialize <code>Active</code> and <code>Tag</code> on bodies. Do not rely on those additions for an entity intended to remain portable across all three editors.

== Attachments ==

The '''Attachments''' tab filters which object types can be selected. Press '''Attach''', then click eligible objects to add or remove them from the pending attachment set. Press '''Done''' or finish the tool to commit the set. '''Clear attachments''' removes the body's current child-object references.

An attachment is not a collision shape. Shapes define the body's collision geometry; attached child objects follow the body. A common rigid prop therefore has one or more shapes and one or more attached submeshes, all referenced by the same body.

== Verification and troubleshooting ==

Before considering a body finished:

* inspect the entity from several orthographic views so the shapes actually enclose the intended collision volume;
* verify that every shape belongs to the intended body and that no unwanted shape was included in a multi-selection;
* check that visual parts which should move are attached to the correct body;
* use a physics material name available in the active game or mod configuration;
* check character and non-character collision independently;
* test gravity, surface effects, and continuous collision under the speeds the entity will encounter; and
* if joints are present, verify their parent and child body assignments after renaming or rebuilding bodies.

The Model Editor and engine can fall back to a default physics material when a named material cannot be loaded, so an entity appearing to collide is not proof that its requested material resolved correctly. Check <code>ModelEditor.log</code> and the game log for material-loading errors.

== See also ==

* [[HPL3/Entities/Working with Shapes|Working with Shapes]]
* [[HPL3/Entities/Physics Body Properties|Physics Body Properties]]
* [[HPL3/SOMA/Entities/Working with Joints|Working with Joints]]

[[Category:English]]

HPL3/Entities/Entity Notes

2026-10-02T17:34:21Z

TiMan: Create shared HPL3 Entity Notes guide, preserving the existing SOMA article purpose and image and adding verified serialization details

'''Entity Notes''' are free-form authoring notes attached to an entity file. They are intended for information that another level designer should see when using the entity, rather than for text shown to the player during gameplay.

[[File:window_entitynotes.png]]

== Adding a note ==

# Open the entity in the Model Editor.
# Open the '''Notes''' window.
# Type the information in its text box.
# Close the window and save the entity.

No separate confirmation step is required in the Notes window; saving the entity commits the current note along with the rest of the entity data.

Useful notes include setup requirements, intended orientation, required companion objects, known limitations, and warnings about entity variables. Keep them short enough to read while placing the entity.

== Storage ==

When a note is present, the Model Editor stores it as a top-level element in the <code>.ent</code> file:

<syntaxhighlight lang="xml">
<Notes Content="Place against a wall and align the main body with the floor." />
</syntaxhighlight>

The <code>Notes</code> element is separate from <code>ModelData</code>, <code>UserDefinedVariables</code>, and <code>EditorSession</code>. Most shipped entities omit it because they have no authoring note. All three inspected HPL3 Model Editor and Level Editor builds contain support for the <code>Notes</code> element and its <code>Content</code> field.

In the Level Editor, the note can be read through the entity-notes interface when working with an entity of that type. Entity Notes are therefore documentation for editors; they are not the same as a readable note, journal entry, localization key, or an entity type's gameplay variable named “Note.”

== See also ==

* [[HPL3/Entities/Entity Settings|Entity Settings]]
* [[HPL3/Entities/Model Editor View|Model Editor View]]

[[Category:English]]

HPL3/Entities/Model Editor Preferences

2026-10-02T17:34:19Z

TiMan: Create shared HPL3 Model Editor preferences guide from installed editor configuration and persistence files

The Model Editor's '''Preferences''' window contains application-level settings shared by the Model Editors shipped with SOMA, Amnesia: Rebirth, and Amnesia: The Bunker.

== Preferences window ==

Open '''Preferences''' from the editor menu. The common controls are:

* '''Resolution''': the editor window's width and height.
* '''Undo stack size''': the number of editor actions retained for undo.

A larger undo stack retains more editing history but requires more memory. Resolution is stored as two values, corresponding to the horizontal and vertical window dimensions.

== Configuration files ==

The editor uses several files with separate responsibilities. By default, their home directory is the <code>HPL3</code> folder under the user's documents directory; the actual resolved home directory is printed in <code>ModelEditor.log</code> when the editor starts.

{| class="wikitable"
! File !! Purpose
|-
| <code>MainEditorSettings.cfg</code> || Defines the editor home, temporary, thumbnail, and session directory names. The three shipped games use <code>HPL3</code>, <code>Temp</code>, <code>Thumbnails</code>, and <code>Sessions</code> respectively.
|-
| <code>ModelEditor.prf</code> || Stores Model Editor preference data. A file containing only <code><Preferences /></code> represents no explicitly saved non-default values.
|-
| <code>ModelEditor.cfg</code> || Stores other application state, including screen size, graphics/performance values, and recent entity files.
|-
| <code>ModelEditor.log</code> || Records startup paths, initialized subsystems, loaded resources, warnings, and errors.
|}

These files are not entity assets and should not be distributed as part of an entity. If preferences appear not to persist, close the editor normally and check the home directory reported in the log. A redirected Documents folder can place the files somewhere other than the conventional local Documents path.

== Per-entity state is separate ==

Viewport camera, render, grid, and enlargement state can be saved inside an entity's <code>EditorSession</code>. Those settings belong to the <code>.ent</code> file and are not controlled by the application-level Preferences window. See [[HPL3/Entities/Model Editor Controls|Model Editor Controls]] for the saved viewport fields.

[[Category:English]]

HPL3/Entities/Model Editor Controls

2026-10-02T17:34:18Z

TiMan: Create shared HPL3 Model Editor controls guide verified against the SOMA, Rebirth, and Bunker editor executables and entity sessions

The '''Model Editor controls''' combine object-editing modes with per-viewport camera and display controls. The core controls described here are present in the Model Editors shipped with SOMA, Amnesia: Rebirth, and Amnesia: The Bunker.

== Object editing ==

The editor provides four main object modes:

* '''Select''' chooses objects in a viewport and exposes their editable properties.
* '''Translate''' moves the selection.
* '''Rotate''' rotates the selection.
* '''Scale''' changes its size.

The editor also provides '''Clone''', '''Delete''', '''Undo''', and '''Redo''' commands. Keep an eye on the current selection and active mode before dragging: the same pointer movement has a different effect in selection, translation, rotation, and scaling modes.

'''Focus''' frames the current selection in a viewport. This is useful after importing a model at an unexpected scale or moving the camera away from the entity.

== Viewports ==

A normal Model Editor layout contains orthographic '''Front''', '''Right''', and '''Top''' views and a '''Perspective''' view. Each viewport stores its own camera and display state.

The viewport menu includes:

* '''Camera Mode''': selects the view orientation.
* '''Render Mode''': selects the display style, including shaded and wireframe rendering.
* '''Controller''': selects camera navigation. Shipped entity sessions use '''Ortho''' for the three orthographic views and '''Maya''' for the perspective view; '''Fly''' is also available in all three editors.
* '''Show Grid''' and '''Show Axes''': toggle those viewport guides.

The focused viewport can be enlarged and later returned to the four-view layout. Saved <code>.ent</code> files may retain the focused viewport, enlargement state, camera position and target, controller, view mode, renderer, axes, grid, and grid-plane state in <code>EditorSession/ViewportConfig</code>.

== Grid and snapping ==

The lower controls select a grid plane and maintain grid height and snapping state. The active plane matters in orthographic work: shipped sessions normally associate Front, Right, and Top with different grid planes.

Use snapping when collision shapes, sockets, or other components must share an exact position. Turn it off for fine visual alignment. Because the saved viewport session records <code>GridPlane</code>, <code>GridHeights</code>, and <code>LockToGrid</code>, reopening two entities can restore different grid states.

== Shortcut differences ==

Do not assume that every HPL3 Model Editor build displays the same keyboard hints. For example, the later Amnesia editors expose help strings for focusing the selection and toggling grid snapping that are not exposed in the same form by the SOMA executable. Use the command labels and tooltips shown by the editor build you are running.

== See also ==

* [[HPL3/Entities/Model Editor View|Model Editor View]]
* [[HPL3/Entities/Model Editor Preferences|Model Editor Preferences]]
* [[HPL3/Entities/Working with Shapes|Working with Shapes]]

[[Category:English]]

HPL3/Amnesia: The Bunker/Third Party Tools

2026-10-02T17:25:21Z

TiMan: Created page with "'''These tools have been created by third parties, some which are members of the community, and are not affiliated with Frictional Games.''' {{CategoryHeader}} {{CategoryNewc..."

'''These tools have been created by third parties, some which are members of the community, and are not affiliated with Frictional Games.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Community-Made Tools ==
* [[HPL3/Third_Party_Tools/HPL3_Mod_Manager|HPL3 Mod Manager]]
* [[HPL3/Blender_HPL3_export_plugin|Blender HPL3 export plugin]]

== Programming Tools ==
* [[CodeLite|CodeLite]]
* [[Visual Studio Code|Visual Studio Code]]

{{CategoryNewcolumn}}

== 3D Design Tools ==
* [[Autodesk Maya|Autodesk Maya]]
* [[Modo|Modo]]
* [[Blender|Blender]]

== 2D Design Tools ==
* [[GIMP|GIMP]]
* [[Adobe Photoshop|Adobe Photoshop]]

== Audio Tools ==
* [[Audacity|Audacity]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: The Bunker/Glossary

2026-10-02T17:24:54Z

TiMan: Created page with "{{stub}} '''Find explanations of various HPL3 terms here.''' {{CategoryHeader}} {{CategoryNewcolumn}} == General == *'''Static Object''' - An in-game object which is used on..."

{{stub}}
'''Find explanations of various HPL3 terms here.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== General ==
*'''Static Object''' - An in-game object which is used only for physics collisions. They can't be influenced by scripts.
*'''Entity''' - An in-game object which allows interaction.
*'''Prop''' - A type of entity which can be collected and added to the player's inventory.
*'''Area''' - Invisible in-game cuboid which marks 3D space. Used as an input-output systems for the levels.

== Modding ==
*'''Mod''' - Additional game content created by community members and fans.
*'''Custom Story''' - User-made content available from the game's main menu or from a designated launcher. They use all settings from the config files the game was started with, which limits what the creator can change (for example being forced to use the default lantern). This is the type of creation recommended for beginners.
*'''Mod Dependency''' - A mod which is being used by other mods as a source for content.

== Level Design ==

== Scripting ==
*'''Script''' - Written code which determines what happens in a map. This includes events, puzzles, music, and more.
*'''User Module''' - Script files which always run in the background and usually define the behavior or core mechanics in the game.
*'''Handler''' - A synonym for a User Module.

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Animation

2026-10-02T17:21:10Z

TiMan:

'''This category deals with 3D animation in SOMA.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/SOMA/Animation/Animation Overview|Animation Overview]]

== General ==
* [[HPL3/SOMA/Modeling/Animation Principles|Animation Principles]]
* [[HPL3/SOMA/Modeling/Importing Animations|Importing Animations]]
* [[HPL3/SOMA/Modeling/Exporting Animations|Exporting Animations]]
* [[HPL3/SOMA/Modeling/Animation Principles|Animation Lipsync]]

{{CategoryNewcolumn}}

== Tools ==
* [[Autodesk Maya]]
* [[Blender]]
* [[HPL3/Blender_HPL3_export_plugin|HPL3 Blender Exporting Tool]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Animation/Exporting Animations

2026-10-02T17:17:40Z

TiMan: Add a compatibility Animation-namespace title for the SOMA Exporting Animations guide.

#REDIRECT [[HPL3/SOMA/Modeling/Exporting Animations]]

HPL3/SOMA/Animation/Importing Animations

2026-10-02T17:17:39Z

TiMan: Add a compatibility Animation-namespace title for the SOMA Importing Animations guide.

#REDIRECT [[HPL3/SOMA/Modeling/Importing Animations]]

HPL3/SOMA/Modeling/Exporting Animations

2026-10-02T17:16:50Z

TiMan: Add a SOMA-file-verified animation export guide covering hierarchy compatibility, source formats, cache generation, first-success testing, and troubleshooting.

'''Exporting an animation''' creates a source clip that SOMA can register on an entity. SOMA's shipped entities use <code>.dae_anim</code> and <code>.fbx</code> animation sources; the engine generates <code>.anm</code> cache files from supported sources.

This guide describes requirements visible in SOMA's shipped files and executables. Exact menu names and exporter options depend on the 3D application and exporter version.

== Start from the entity mesh ==

Use the same production rig or animated node hierarchy used to export the entity mesh.

* Keep node and bone names stable. Exported animation channels target names such as <code>joint1/matrix</code> or <code>ball/translate.Y</code>.
* Keep hierarchy changes deliberate. SOMA reports a mismatch when the skeleton in the mesh differs from the skeleton saved in the entity.
* Keep the mesh and clips on a consistent scale convention. The installed <code>.dae_anim</code> files carry unit metadata with several labels and factors, so the label alone is not a reliable project rule; verify the resulting movement against the imported mesh.
* Use an axis configuration known to work for that asset pipeline. Of 876 installed <code>.dae_anim</code> files, 869 declare <code>Y_UP</code> and seven declare <code>Z_UP</code>.
* Ensure every skinned vertex has a valid bone assignment and no more than four bone influences. SOMA contains explicit diagnostics for both failures.

== Prepare one clip per action ==

Export separate source files for independently selectable actions such as <code>idle</code>, <code>open</code>, <code>close</code>, or a transition between two poses.

Before export:

# Set the intended start and end of the clip.
# Remove unrelated animation takes or actions from the export selection.
# Include the bones or animated nodes needed by the entity.
# Preserve the bind/rest relationship expected by the mesh.
# Decide whether the clip should loop. For a loop, compare the first and last poses and remove an unintended visible jump.
# Export to the final mod-relative animation directory.

Do not bake sounds, particles, or gameplay callbacks into assumptions about the source format. SOMA stores those as events in the entity's animation registration.

== Choose a source format ==

=== Collada animation source ===

SOMA ships 876 <code>.dae_anim</code> files. Each is a Collada XML document and every inspected file contains at least one animation channel. The sources contain between 1 and 487 channels, targeting matrices, visibility, rotation, translation, and scale.

The extension distinguishes an animation source from a normal <code>.dae</code> mesh file, but shipped <code>.dae_anim</code> files can still contain geometry, materials, controllers, and scene data in addition to animation channels.

Seventy-one shipped <code>.dae_anim</code> files retain explicit OpenCOLLADA export-option comments. All 71 record animation and joint/skin export as enabled. They do not use one universal sampling setting: 15 record sampling enabled and 56 disabled. Likewise, static-curve removal varies. These values show that one copied exporter preset is not valid for every shipped clip.

=== FBX animation source ===

SOMA entities contain 110 registrations referencing <code>.fbx</code> animation files. This proves that the shipped pipeline uses FBX clips, but not that every modern FBX version or exporter setting is compatible with SOMA's older importer. Test a minimal clip before committing to a production pipeline.

== Generate and inspect the cache ==

Place the source file in its final resource directory, then load it through the Model Editor or an entity that references it. SOMA uses same-stem <code>.anm</code> files as compiled animation data.

Examples from the installed game include:

<pre>
shower_curtain_open.fbx → shower_curtain_open.anm
ventilation_cluster_spin.dae_anim → ventilation_cluster_spin.anm
</pre>

Do not hand-edit the binary <code>.anm</code>. Re-export the source and let the engine/tool pipeline refresh generated data. SOMA reports when an animation source cannot be found or compiled.

== First-success export test ==

# Export a short clip that moves one clearly identifiable bone or node.
# Put it beside the target entity or in that entity's animation subdirectory.
# Add it to the entity with a unique name, <code>Speed=1</code>, and no events or transitions.
# Preview the clip and enable skeleton display.
# Confirm the expected node moves, the mesh keeps its scale, and the start/end frames are correct.
# Save and reopen the entity, then play the registered name in a test map.
# Only after this succeeds, export the remaining clips and add events or transitions.

The shipped <code>ventilation_cluster_spin.dae_anim</code> is a useful structural example: it declares ten channels targeting <code>root</code> and eight joint matrices plus root visibility, and its entity registers the clip on the <code>Default</code> layer with a speed of <code>1.2</code>.

== Troubleshooting ==

* '''The clip cannot be found:''' verify the exported file path, extension, filename case, and <code>resources.cfg</code> coverage.
* '''Nothing moves:''' confirm the source contains animation channels and that their target names exist in the entity mesh hierarchy.
* '''The mesh scales or offsets unexpectedly:''' compare mesh and animation unit metadata, axis settings, root transforms, and bind/rest setup.
* '''Only part of a skinned mesh follows:''' check for unweighted vertices and excessive bone influences; SOMA explicitly diagnoses both.
* '''The entity reports a skeleton mismatch:''' reimport the mesh into the entity and export the animation from the matching hierarchy.
* '''A loop jumps:''' inspect the first and last poses and the intended playback range in the source application.
* '''Old motion persists after export:''' reload the entity and refresh the generated <code>.anm</code> cache.

== See also ==

* [[HPL3/SOMA/Animation/Animation Overview|Animation Overview]]
* [[HPL3/SOMA/Modeling/Importing Animations|Importing Animations]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Blender HPL3 export plugin|Blender HPL3 export plugin]]

[[Category:English]]

HPL3/SOMA/Modeling/Importing Animations

2026-10-02T17:16:49Z

TiMan: Add a SOMA-file-verified animation import guide covering entity registration, caches, preview, events, transitions, script testing, and troubleshooting.

'''Importing an animation''' registers an exported animation source on a SOMA entity so the clip can be previewed and played by name.

== Before importing ==

Confirm that:

* the entity already loads its intended animated mesh;
* the exported animation uses the mesh's node or bone names;
* the animation and mesh were exported with compatible scale and axis settings;
* the animation file is in a directory included by the mod's <code>resources.cfg</code>; and
* the source file has a unique, stable path inside the mod.

SOMA ships entity registrations that reference both <code>.dae_anim</code> and <code>.fbx</code> sources. This establishes support for those installed assets, not compatibility with every exporter version. Verify the chosen exporter with a minimal clip before producing a full animation set.

== Add a clip to an entity ==

# Open the target <code>.ent</code> file in <code>ModelEditor.exe</code>.
# Enable '''Entity Preview''' from the lower toolbar.
# Open '''Edit Animations''' in the preview window.
# Choose '''Add new animation'''.
# Set a unique '''Name''' used by scripts and entity logic.
# Set '''File''' to the exported <code>.dae_anim</code> or <code>.fbx</code> source.
# Use <code>Default</code> for '''Layer''' unless the entity has a known layered setup.
# Begin with '''Speed''' set to <code>1</code>.
# Save the entity and select the new animation in the preview controls.

The saved entity entry has this basic form:

<syntaxhighlight lang="xml">
<Animations>
<Animation
Name="open"
File="entities/urban/toilet/shower_curtain/shower_curtain_open.fbx"
Layer="Default"
Speed="1"
/>
</Animations>
</syntaxhighlight>

This example is taken from SOMA's shipped <code>shower_curtain.ent</code>. The animation's registered name is <code>open</code>; scripts play that name, not the filename.

== Understand source and cache files ==

SOMA stores compiled animation data in <code>.anm</code> files. After deduplicating the paths referenced by shipped entity animation registrations:

* 939 non-empty source paths are registered;
* 879 corresponding source files are present in the installation;
* 866 of those present sources have a same-stem <code>.anm</code> file;
* 785 of those pairs use <code>.dae_anim</code> sources; and
* 81 use <code>.fbx</code> sources.

For example:

<pre>
ventilation_cluster_spin.dae_anim
ventilation_cluster_spin.anm
</pre>

The source is the file registered on the entity. Treat <code>.anm</code> as generated engine data. When replacing a source animation, reload the entity and verify that the cache was refreshed rather than editing the cache manually.

== Preview and validate ==

Use Entity Preview to check:

* whether the animation appears in the selector;
* whether it plays at the expected speed;
* whether looping behaves correctly;
* whether the skeleton moves without unexpected scaling or offsets;
* whether the first and last poses meet correctly for a loop; and
* whether physical bodies, sockets, and attached effects remain aligned.

The preview window can display the skeleton and physical objects and provides play, loop, step, time, and timeline controls.

SOMA's executable reports useful failures, including missing animation files, skeleton differences between the mesh and saved entity, vertices without a bone, vertices influenced by more than four bones, and missing transition animations.

== Add events ==

Events are added to the registered animation in the Model Editor, not baked into the exported source file. Each shipped event record stores a name, time, type, destination socket, and value.

Available event types declared by SOMA include:

* <code>PlaySound</code>
* <code>CreateParticle</code>
* <code>Step</code>
* <code>Message</code>
* <code>PlayLoopSound</code>
* <code>StopLoopSound</code>

Add an event at the intended timeline position, choose its type, and provide the resource or socket required by that type. Test it in preview and in-game. A valid animation can still have a failing event if its sound, particle system, or destination socket is missing.

SOMA's <code>robot_arm_welding.ent</code> demonstrates timed loop sounds, ordinary sounds, particles attached to sockets, and a stop-loop event on one animation.

== Add transitions ==

A transition registers a separate bridge clip to use when entering the selected animation from a previous animation.

# Register the base, target, and bridge clips as ordinary animations first.
# Confirm that each clip plays independently.
# Add a transition to the target animation.
# Set the previous animation and the bridge-animation name.
# Adjust the minimum and maximum previous-animation time only when the transition should be limited to a time window.
# Enable transition preview and test every route that can select the target animation.

SOMA's shipped entities contain 204 transition entries. The engine emits separate errors for a missing previous animation, missing transition animation, and missing transition base animation.

== Test from script ==

After preview succeeds, place the entity in a test map and play the registered name:

<syntaxhighlight lang="cpp">
Entity_PlayAnimation("Machine", "open", 0.1f, false, true, "OnAnimationFinished");
</syntaxhighlight>

The SOMA API records the completion callback as:

<syntaxhighlight lang="cpp">
void OnAnimationFinished(const tString &in asEntityName,
const tString &in asAnimName)
{
}
</syntaxhighlight>

Use a loop only for a clip intended to repeat. Leave transition playback enabled only when the entity has a matching transition setup.

== Troubleshooting ==

* '''The file does not appear or load:''' verify the mod-relative path, extension, and resource configuration.
* '''The animation name cannot be played:''' check the entity's registered <code>Name</code>; it can differ from the source filename.
* '''The mesh deforms incorrectly:''' compare the mesh and animation hierarchy, node names, unit metadata, and export axes.
* '''The entity reports a skeleton mismatch:''' reimport the mesh into the entity and confirm that the exported animation targets that same skeleton.
* '''Events do not fire correctly:''' inspect event time, type, value, and socket separately from animation playback.
* '''A transition fails:''' verify that the previous, target, and bridge names all match registered entity animations.
* '''An update still plays old data:''' reload the entity after replacing the source and ensure the generated <code>.anm</code> cache is refreshed.

== See also ==

* [[HPL3/SOMA/Animation/Animation Overview|Animation Overview]]
* [[HPL3/SOMA/Modeling/Exporting Animations|Exporting Animations]]
* [[HPL3/Entities/Adding Animations to Entities|Animation Editor fields]]
* [[HPL3/Entities/Model Preview Settings|Entity Preview]]

[[Category:English]]

HPL3/SOMA/Animation/Animation Overview

2026-10-02T17:16:47Z

TiMan: Add a SOMA-file-verified animation overview covering source/cache formats, entity registration, skeleton compatibility, events, transitions, scripting, and workflow.

An '''animation''' changes an entity's mesh over time. In SOMA, an exported animation source is registered on an entity under a playable name. Scripts and entity logic play that registered name rather than referring to the source filename directly.

== Animation pipeline ==

A typical SOMA animation passes through four stages:

# A mesh and its skeleton or animated nodes are prepared in a 3D application.
# Each animation clip is exported to a source file, usually <code>.dae_anim</code> or <code>.fbx</code> in the shipped game.
# The clip is added to an entity's <code>Animations</code> section in <code>ModelEditor.exe</code>, where it receives a name and playback settings.
# Loading the source produces an <code>.anm</code> cache used by the engine.

The installed SOMA entities contain 1,490 animation registrations. Of these, 1,379 reference <code>.dae_anim</code> files and 110 reference <code>.fbx</code> files. After deduplicating those registrations, 879 referenced source files are present in the installation; 866 have a same-stem <code>.anm</code> cache.

The source file remains the editable input. The <code>.anm</code> is generated engine data, not a replacement for the source animation.

== Entity animation registration ==

Animations are stored inside the entity's <code>Animations</code> element. A simple shipped registration is:

<syntaxhighlight lang="xml">
<Animation
Name="open"
File="entities/urban/toilet/shower_curtain/shower_curtain_open.fbx"
Layer="Default"
Speed="1"
/>
</syntaxhighlight>

This entry belongs to <code>entities/urban/toilet/shower_curtain/shower_curtain.ent</code>. The same entity's mesh is <code>shower_curtain.fbx</code>; the entity records seven bones and uses a separate <code>shower_curtain_open.anm</code> cache for the animation source.

{| class="wikitable"
! Attribute !! Purpose established by SOMA data
|-
| <code>Name</code> || Name used by scripts and entity behavior to select the animation.
|-
| <code>File</code> || Mod-relative path to the exported animation source.
|-
| <code>Layer</code> || Animation layer. <code>Default</code> is present on 1,387 of the 1,490 inspected registrations; 103 registrations omit this attribute.
|-
| <code>Speed</code> || Playback-speed multiplier. <code>1</code> is the most common shipped value, but SOMA also uses values below and above 1.
|-
| <code>SpecialEventTime</code> || Optional stored time value present on 103 inspected registrations. Its exact runtime purpose is not documented by the inspected scripts, so it should not be assigned a meaning without testing.
|}

== Skeleton and channel compatibility ==

An animation source contains channels targeting named nodes or bones. All 876 installed <code>.dae_anim</code> files parsed successfully and contain at least one channel. Targets include transformation matrices, translation, rotation, scale, and visibility.

The animation must match the entity mesh's expected hierarchy closely enough for those targets to resolve. SOMA's executable reports specific errors when:

* the skeleton stored in the mesh differs from the skeleton saved in the <code>.ent</code> file;
* vertices in a skinned submesh are not connected to a bone;
* a vertex is influenced by more than four bones; or
* an animation, transition animation, previous animation, or socket cannot be found.

Treat bone and node names as stable identifiers. Re-exporting the mesh with renamed or reorganized bones can invalidate both saved entity data and existing animation clips.

== Events and transitions ==

Animation behavior can be extended in the Model Editor without changing the source clip.

=== Events ===

An event is attached to a time in a registered animation. The 580 inspected shipped event entries all store <code>Name</code>, <code>Time</code>, <code>Type</code>, <code>DestSocket</code>, and <code>Value</code>. Event types used by shipped SOMA entities are:

* <code>PlaySound</code>
* <code>PlayLoopSound</code>
* <code>StopLoopSound</code>
* <code>CreateParticle</code>
* <code>Message</code>

The engine also declares a <code>Step</code> event type, although no shipped event of that type was found in the inspected entity registrations.

For example, <code>robot_arm_welding.ent</code> attaches looped movement sound, weld sounds, particle creation at named sockets, and a stop-loop event to its <code>welding</code> animation.

=== Transitions ===

A transition selects a bridging animation when changing from a specified previous animation to the target animation. SOMA's shipped entities contain 204 transition entries. Their stored fields include the transition name, bridging animation name, optional previous-animation name, and minimum/maximum timing values.

Transitions are entity registration data. The source clips for the base and bridge animations must each be exported and registered before the transition can resolve them.

== Playing a registered animation ==

SOMA's script API exposes:

<syntaxhighlight lang="cpp">
void Entity_PlayAnimation(
const tString &in asEntityName,
const tString &in asAnimation,
float afFadeTime = 0.1f,
bool abLoop = false,
bool abPlayTransition = true,
const tString &in asCallback = ""
);
</syntaxhighlight>

The callback signature recorded by the SOMA API is:

<syntaxhighlight lang="cpp">
void Callback(const tString &in asEntityName, const tString &in asAnimName)
</syntaxhighlight>

For entities with a character-mover component, <code>CharMover_PlayAnimation</code> provides the same animation name, fade, loop, transition, and callback concepts through that component.

SOMA also exposes functions to stop an entity animation, pause or resume a named animation, set its relative time position, and receive message-event callbacks.

== Practical workflow ==

# Export one short clip using the same mesh hierarchy, node names, scale convention, and axis setup as the entity mesh.
# Add the clip to the entity in the Model Editor and give it a unique, stable <code>Name</code>.
# Leave <code>Speed</code> at <code>1</code> for the first test and use the default layer unless the entity has a verified layered setup.
# Open Entity Preview, select the registered animation, and test playback, looping, the skeleton display, and the timeline.
# Add events only after basic playback works. Verify referenced sockets, sounds, and particle systems separately.
# Add transitions only after every base and bridge animation plays by itself.
# Save the entity, place it in a test map, and play the registered name from the relevant entity logic or script.

== See also ==

* [[HPL3/SOMA/Modeling/Exporting Animations|Exporting Animations]]
* [[HPL3/SOMA/Modeling/Importing Animations|Importing Animations]]
* [[HPL3/Entities/Adding Animations to Entities|Animation registration controls]]
* [[HPL3/Entities/Model Preview Settings|Entity Preview controls]]
* [[HPL3/SOMA/Audition/Lip Sync|Lip Sync]]

[[Category:English]]

HPL3/Amnesia: Rebirth/Tutorials

2026-10-02T17:14:52Z

TiMan: /* Modding */

{{stub}}
'''Find tutorials of various HPL3 topics here.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Modding ==
* [[HPL3/Amnesia: Rebirth/Tutorials/FAQ|FAQ]]
* [[HPL3/Amnesia: Rebirth/Tutorials/Custom Menu| Custom Menu]]

== Level Design ==

== Gameplay ==

== Systems ==
* [[HPL3/Amnesia: Rebirth/Tutorials/Notes| Creating and Managing Notes]]
* [https://www.youtube.com/watch?v=L_6mU5oC9Lk Custom sounds using FMOD 2010 (Video)]

== Scripting ==

== Agents ==
* [[HPL3/Amnesia:_The_Bunker/Tutorials/Stalker| Stalker Setup]]

== 3D ==

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: Rebirth/Tutorials

2026-10-02T17:14:40Z

TiMan: /* Gameplay */

{{stub}}
'''Find tutorials of various HPL3 topics here.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Modding ==
* [[HPL3/Amnesia: Rebirth/Tutorials/FAQ|FAQ]]
* [https://www.youtube.com/watch?v=-jFnEk7peTE&list=PL4KkjlmOwLwwMVqedCNpi6caUxhgyf8Qr| Custom Story Creation Tutorial Series - By TechOFreak128]
* [[HPL3/Amnesia: Rebirth/Tutorials/Custom Menu| Custom Menu]]

== Level Design ==

== Gameplay ==

== Systems ==
* [[HPL3/Amnesia: Rebirth/Tutorials/Notes| Creating and Managing Notes]]
* [https://www.youtube.com/watch?v=L_6mU5oC9Lk Custom sounds using FMOD 2010 (Video)]

== Scripting ==

== Agents ==
* [[HPL3/Amnesia:_The_Bunker/Tutorials/Stalker| Stalker Setup]]

== 3D ==

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: Rebirth/Tutorials

2026-10-02T17:14:34Z

TiMan: /* Agents */

{{stub}}
'''Find tutorials of various HPL3 topics here.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Modding ==
* [[HPL3/Amnesia: Rebirth/Tutorials/FAQ|FAQ]]
* [https://www.youtube.com/watch?v=-jFnEk7peTE&list=PL4KkjlmOwLwwMVqedCNpi6caUxhgyf8Qr| Custom Story Creation Tutorial Series - By TechOFreak128]
* [[HPL3/Amnesia: Rebirth/Tutorials/Custom Menu| Custom Menu]]

== Level Design ==

== Gameplay ==
* [[HPL3/Amnesia: Rebirth/Tutorials/Rifts| Rifts]]
* [[HPL3/Amnesia: Rebirth/Tutorials/Tablets | Dark World Tablets]]
* [[HPL3/Amnesia: Rebirth/Tutorials/Inventory items| Custom inventory items]]

== Systems ==
* [[HPL3/Amnesia: Rebirth/Tutorials/Notes| Creating and Managing Notes]]
* [https://www.youtube.com/watch?v=L_6mU5oC9Lk Custom sounds using FMOD 2010 (Video)]

== Scripting ==

== Agents ==
* [[HPL3/Amnesia:_The_Bunker/Tutorials/Stalker| Stalker Setup]]

== 3D ==

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: The Bunker/Modding

2026-10-02T17:11:33Z

TiMan:

'''This category deals with creating, managing and releasing Amnesia: The Bunker mods, including managing and organizing a team.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== General Advice ==
* [[Making a Mod - Best Practices]]
* [[Online Presence]]
* [[Efficient Teamwork]]

== Getting Started ==
* [[HPL3/Amnesia: The Bunker/Modding/Creating a Mod|Creating a Mod]]
* [[HPL3/Amnesia: The Bunker/Modding/Setup Modding Environment|Setup Modding Environment]]
* [[Setting up an Online Repository|Setting up an Online Repository]]
* [[HPL3/Amnesia: The Bunker/Developer Commands|Developer Commands]]
* [[HPL3/Amnesia: The Bunker/Modding/Developer Debug Menu|Developer Debug Menu]]
* [[Mod Content Usage|Mod Content Usage]]

== Releasing ==
* [[Pre-Publication Evaluation]]
* [[Mod Distribution]]

== Community ==
* [https://discord.com/invite/frictionalgames Discord Server]
* [https://www.moddb.com/games/soma/mods ModDB Homepage]

{{CategoryNewcolumn}}

== Mod Configuration ==
* [[HPL3/Resources Configuration|Resources Configuration (Custom Assets)]]
* [[HPL3/Launch Configuration|Launch Configuration]]
* [[HPL3/Language Configuration|Language Configuration]]
* [[HPL3/Modding/Mod Dependencies|Mod Dependencies]]

== Resources ==
*[[HPL3/Amnesia: The Bunker/Modding/MinimalCustomMapMod|Minimal Custom Map Mod]]

== Tools ==
*[[HPL3/Amnesia: Rebirth/Third_Party_Tools/Amnesia: Rebirth Mod Manager|Amnesia: The Bunker Mod Manager]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: The Bunker/Modding

2026-10-02T17:10:45Z

TiMan: /* Tools */

'''This category deals with creating, managing and releasing Amnesia: Rebirth mods, including managing and organizing a team.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== General Advice ==
* [[Making a Mod - Best Practices]]
* [[Online Presence]]
* [[Efficient Teamwork]]

== Getting Started ==
* [[HPL3/Amnesia: The Bunker/Modding/Creating a Mod|Creating a Mod]]
* [[HPL3/Amnesia: The Bunker/Modding/Setup Modding Environment|Setup Modding Environment]]
* [[Setting up an Online Repository|Setting up an Online Repository]]
* [[HPL3/Amnesia: The Bunker/Developer Commands|Developer Commands]]
* [[HPL3/Amnesia: The Bunker/Modding/Developer Debug Menu|Developer Debug Menu]]
* [[Mod Content Usage|Mod Content Usage]]

== Releasing ==
* [[Pre-Publication Evaluation]]
* [[Mod Distribution]]

== Community ==
* [https://discord.com/invite/frictionalgames Discord Server]
* [https://www.moddb.com/games/soma/mods ModDB Homepage]

{{CategoryNewcolumn}}

== Mod Configuration ==
* [[HPL3/Resources Configuration|Resources Configuration (Custom Assets)]]
* [[HPL3/Launch Configuration|Launch Configuration]]
* [[HPL3/Language Configuration|Language Configuration]]
* [[HPL3/Modding/Mod Dependencies|Mod Dependencies]]

== Resources ==
*[[HPL3/Amnesia: The Bunker/Modding/MinimalCustomMapMod|Minimal Custom Map Mod]]

== Tools ==
*[[HPL3/Amnesia: Rebirth/Third_Party_Tools/Amnesia: Rebirth Mod Manager|Amnesia: The Bunker Mod Manager]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: The Bunker/Modding

2026-10-02T17:10:30Z

TiMan:

'''This category deals with creating, managing and releasing Amnesia: Rebirth mods, including managing and organizing a team.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== General Advice ==
* [[Making a Mod - Best Practices]]
* [[Online Presence]]
* [[Efficient Teamwork]]

== Getting Started ==
* [[HPL3/Amnesia: The Bunker/Modding/Creating a Mod|Creating a Mod]]
* [[HPL3/Amnesia: The Bunker/Modding/Setup Modding Environment|Setup Modding Environment]]
* [[Setting up an Online Repository|Setting up an Online Repository]]
* [[HPL3/Amnesia: The Bunker/Developer Commands|Developer Commands]]
* [[HPL3/Amnesia: The Bunker/Modding/Developer Debug Menu|Developer Debug Menu]]
* [[Mod Content Usage|Mod Content Usage]]

== Releasing ==
* [[Pre-Publication Evaluation]]
* [[Mod Distribution]]

== Community ==
* [https://discord.com/invite/frictionalgames Discord Server]
* [https://www.moddb.com/games/soma/mods ModDB Homepage]

{{CategoryNewcolumn}}

== Mod Configuration ==
* [[HPL3/Resources Configuration|Resources Configuration (Custom Assets)]]
* [[HPL3/Launch Configuration|Launch Configuration]]
* [[HPL3/Language Configuration|Language Configuration]]
* [[HPL3/Modding/Mod Dependencies|Mod Dependencies]]

== Resources ==
*[[HPL3/Amnesia: The Bunker/Modding/MinimalCustomMapMod|Minimal Custom Map Mod]]

== Tools ==
*[[HPL3/Amnesia: Rebirth/Third_Party_Tools/Amnesia: Rebirth Mod Manager|Amnesia: Rebirth Mod Manager]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Amnesia: The Bunker/Modding

2026-10-02T17:09:28Z

TiMan: Created page with "'''This category deals with creating, managing and releasing Amnesia: Rebirth mods, including managing and organizing a team.''' {{CategoryHeader}} {{CategoryNewcolumn}} == G..."

'''This category deals with creating, managing and releasing Amnesia: Rebirth mods, including managing and organizing a team.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== General Advice ==
* [[Making a Mod - Best Practices]]
* [[Online Presence]]
* [[Efficient Teamwork]]

== Getting Started ==
* [[HPL3/Amnesia: Rebirth/Modding/Creating a Mod|Creating a Mod]]
* [[HPL3/Amnesia: Rebirth/Modding/Setup Modding Environment|Setup Modding Environment]]
* [[Setting up an Online Repository|Setting up an Online Repository]]
* [[HPL3/Amnesia: Rebirth/Developer Commands|Developer Commands]]
* [[HPL3/Amnesia: Rebirth/Modding/Developer Debug Menu|Developer Debug Menu]]
* [[Mod Content Usage|Mod Content Usage]]

== Releasing ==
* [[Pre-Publication Evaluation]]
* [[Mod Distribution]]

== Community ==
* [https://discord.com/invite/frictionalgames Discord Server]
* [https://www.moddb.com/games/soma/mods ModDB Homepage]

{{CategoryNewcolumn}}

== Mod Configuration ==
* [[HPL3/Resources Configuration|Resources Configuration (Custom Assets)]]
* [[HPL3/Launch Configuration|Launch Configuration]]
* [[HPL3/Language Configuration|Language Configuration]]
* [[HPL3/Modding/Mod Dependencies|Mod Dependencies]]

== Resources ==
*[[HPL3/Amnesia: Rebirth/Modding/MinimalCustomMapMod|Minimal Custom Map Mod]]
*[[HPL3/Amnesia: Rebirth/Modding/Amnesia: Rebirth Language Editor|Language Editor]]

== Tools ==
*[[HPL3/Amnesia: Rebirth/Third_Party_Tools/Amnesia: Rebirth Mod Manager|Amnesia: Rebirth Mod Manager]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Animation

2026-10-02T17:08:10Z

TiMan: /* Tools */

HPL3/SOMA/Areas

2026-10-02T15:31:57Z

TiMan:

'''This category covers everything about the Area in the HPL3 Engine and SOMA.'''

{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/Areas|Areas Overview]]

== Engine Areas ==

=== General ===
* [[HPL3/Areas/PlayerStart Area|PlayerStart Area]]
* [[HPL3/Areas/Trigger Area|Trigger Area]]
* [[HPL3/Areas/DoorwayTrigger Area|DoorwayTrigger Area]]
* [[HPL3/Areas/PathNode Area|PathNode Area]]
* [[HPL3/Areas/Sticky Area|Sticky Area]]
* [[HPL3/Areas/InteractAux Area|InteractAux Area]]

=== Effects ===
* [[HPL3/Areas/Fog Area|Fog Area]]
* [[HPL3/Areas/SoundScape Area|Soundscape Area]]
* [[HPL3/Areas/Camera Animation Area|Camera Animation Area]]
* [[HPL3/Areas/Liquid Area|Liquid Area]]
* [[HPL3/Areas/Ambient Light Area|Ambient Light Area]]
* [[HPL3/Areas/Exposure Area|Exposure Area]]

=== Gameplay ===
* [[HPL3/Areas/Climb Area|Climb Area]]
* [[HPL3/Areas/Crawl Area|Crawl Area]]
* [[HPL3/Areas/Hide Area|Hide Area]]
* [[HPL3/Areas/Ladder Area|Ladder Area]]
* [[HPL3/Areas/Zoom Area|Zoom Area]]

=== Technical ===

* [[HPL3/Areas/Visibility Area|Visibility Area]]
* [[HPL3/Areas/VisibilityPortal Area|VisibilityPortal Area]]
* [[HPL3/Areas/MapTransfer Area|MapTransfer Area]]

{{CategoryNewcolumn}}

== Game-Specific Areas ==
* [[HPL3/SOMA/Areas/Tool Area|Tool Area]]
* [[HPL3/SOMA/Areas/Sit Area|Sit Area]]
* [[HPL3/SOMA/Areas/Distortion Area|Distortion Area]]
* [[HPL3/SOMA/Areas/Datamine Area|Datamine Area]]
* [[HPL3/SOMA/Areas/AgentRepel Area|AgentRepel Area]]

== Unused Areas ==
* [[HPL3/Areas/Description Area|Description Area]]
* [[HPL3/SOMA/Areas/DatamineAudioSource Area|DatamineAudioSource Area]]
* [[HPL3/SOMA/Areas/DatamineAnimNode Area|DatamineAnimNode Area]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Modeling

2026-10-02T15:31:48Z

TiMan:

'''This category deals with 3D modeling in SOMA.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/SOMA/Modeling/Modeling Overview|Modeling Overview]]

== General ==
* [[HPL3/SOMA/Modeling/Modeling Guidelines|Modeling Principles]]
* [[HPL3/SOMA/Modeling/Importing Models|Importing Models]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]

{{CategoryNewcolumn}}

== Tools ==
* [[Autodesk Maya]]
* [[Blender]]
* [[HPL3/Blender_HPL3_export_plugin| HPL3 Blender Exporting Tool]]

{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Modeling/Modeling Guidelines

2026-10-02T15:31:04Z

TiMan: /* Scale, axes, and origin */

'''Modeling principles''' are the preparation rules that make a 3D asset predictable when it is exported, loaded, textured, and given collision in SOMA. They apply before the asset is configured as a static object or an entity.

== Plan the asset's role ==

Decide how the model will be used before splitting the mesh or building collision:

* A '''static object''' is map geometry intended to remain fixed. Nearby static objects with matching material and render settings can be combined by the engine, so reusable architectural pieces benefit from shared materials.
* An '''entity''' is saved as an <code>.ent</code> file and can contain a mesh, physics shapes and bodies, joints, sub-entities, effects, and animations. Its behavior is selected through an entity type.
* A detailed visible mesh and a practical collision shape need not be identical. Complex or rounded visible geometry often benefits from simpler physics shapes configured in the Model Editor.

Use a static object for fixed scenery unless the object needs entity features such as scripted behavior, articulated physics, animation, or per-instance gameplay variables.

== Scale, axes, and origin ==

* Work at a consistent real-world scale. The SOMA export guide recommends treating one unit as one metre, or using centimetres consistently so a one-metre object is 100 units high. Exported unit metadata may be used by the importer.
* Keep the same unit scale for a rigged mesh and all of its animations. The documented result of a mismatch is an animated mesh that expands or shrinks.
* Declare <code>Y_UP</code> as the up axis.
* Place the origin deliberately. The existing SOMA modeling guide recommends positioning an ordinary prop so its bottom is at the origin. This gives a useful placement point on floors; doors, wheels, and other pivoting objects instead need an origin suited to their intended movement.
* Apply or otherwise account for object transforms before export according to the exporter being used. Validate the result in an HPL3 tool rather than assuming the modeling application's displayed scale is authoritative.

== Geometry and submeshes ==

* Give exported objects and mesh datablocks stable, descriptive names. Submesh names matter when an existing entity is reimported and its saved submesh data must be reassigned.
* Export polygon meshes in a form the selected exporter can reliably convert. The shipped Collada example inspected for this guide records triangle export, and the existing Modo and Blender guidance requires triangulation before export.
* Remove accidental duplicate geometry and unused objects from the export selection.
* Split geometry by material where necessary. HPL3 assigns one material to each submesh; a model needing multiple materials therefore needs multiple submeshes.
* Avoid unnecessary submesh and material splits. For static geometry, nearby objects that share a material and compatible settings can be combined at load time, reducing draw calls.
* Keep collision requirements in mind while modeling. Render geometry that is too detailed for collision can use simpler shapes or a separate collision setup in an <code>.ent</code> file.

== UVs and materials ==

* UV-unwrap every textured submesh and keep the UV layout valid for the texture workflow being used.
* Assign the intended diffuse texture to every exported submesh. The importer uses that texture reference to locate the corresponding HPL3 <code>.mat</code> file.
* Match the diffuse texture and material base names. For example, a submesh using <code>panel.dds</code> should have a material named <code>panel.mat</code> available through the resource paths.
* Use distinct texture/material base names for distinct submesh materials, such as <code>door_frame.dds</code>/<code>door_frame.mat</code> and <code>door_leaf.dds</code>/<code>door_leaf.mat</code>.
* Set each material's physics material deliberately when its surface will provide collision. One <code>.mat</code> file has one physics-material setting.

The older SOMA project guide gives historical recommendations for texture formats, suffixes, and relative sizes. Treat those as project conventions, not as proof that every modern mod asset must use the same compression or dimensions. The material file and the current tool output are the authoritative test.

== Organize files predictably ==

Keep an asset's source model, generated cache, materials, textures, and optional entity file in a stable resource directory. A typical entity asset may look like:

<pre>
entities/my_mod/machine/
├── machine.dae
├── machine.msh
├── machine.ent
├── machine.dds
├── machine_nrm.dds
└── machine.mat
</pre>

The exact texture set depends on the material. Same-basename organization is not an engine requirement for every auxiliary texture, but it makes dependencies easier to identify and matches many shipped SOMA assets. In the installed game, 2,944 entity assets have same-basename <code>.ent</code>, <code>.dae</code>, and <code>.msh</code> files.

Make sure the containing directory is included by the mod's <code>resources.cfg</code>. Do not rely on absolute paths embedded by the modeling application; test the asset from its final mod-relative location.

== Validate in small steps ==

# Export the source mesh into its final resource directory.
# Load it in <code>ModelViewer.exe</code> or import it into <code>ModelEditor.exe</code>.
# Check orientation, dimensions, origin, normals, UVs, and material assignment before adding gameplay setup.
# If it will be an entity, save a minimal <code>.ent</code>, then add shapes, bodies, joints, and type variables incrementally.
# Place the static object or entity in a test map and check it in-game under representative lighting.
# Re-export once and verify that the update workflow preserves the intended submesh assignments.

This staged process separates mesh/export problems from material, physics, entity-type, and map-placement problems.

== Common problems ==

* '''Wrong size:''' verify the source scene units and exported unit metadata. For animated assets, verify the mesh and animation use the same scale.
* '''Wrong orientation or pivot:''' fix the source axes/origin and re-export rather than compensating separately in every map instance.
* '''Missing material:''' confirm that the submesh has a diffuse texture reference and that the matching <code>.mat</code> is reachable through the mod resources.
* '''Only one material appears:''' separate faces that need different materials into different exported submeshes.
* '''Collision is expensive or catches on details:''' use simpler Model Editor shapes or a deliberately simplified collider instead of the full visible mesh.
* '''Reimport loses setup:''' keep stable submesh names and review every mapping in the SubMesh Reassign dialog.

== See also ==

* [[HPL3/SOMA/Modeling/Importing Models|Importing Models]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Materials/Working with Materials|Working with Materials]]
* [[HPL3/Entities/Entities Overview|Entities Overview]]
* [[HPL3/Blender HPL3 export plugin|Blender HPL3 export plugin]]

[[Category:English]]

HPL3/SOMA/Modeling/Modeling Principles

2026-10-02T15:29:26Z

TiMan: Add a compatibility title for the Modeling Principles guide linked as Modeling Guidelines by the SOMA Modeling index.

#REDIRECT [[HPL3/SOMA/Modeling/Modeling Guidelines]]

HPL3/SOMA/Modeling/Importing Models

2026-10-02T15:28:59Z

TiMan: Add a practical, source-verified SOMA model-import workflow covering resources, mesh caches, Model Editor import, submesh reassignment, entity setup, testing, and troubleshooting.

'''Importing a model''' brings exported mesh data into SOMA's resource pipeline. The route depends on the intended result:

* A fixed scene piece can be loaded as a '''static object''' from its model file.
* An interactive, animated, or physically configured object should be imported into <code>ModelEditor.exe</code> and saved as an '''entity''' (<code>.ent</code>).

SOMA ships primarily with Collada <code>.dae</code> source models and generated <code>.msh</code> mesh caches. The installed game also contains some <code>.fbx</code> files, especially under <code>entities</code>, but exporter-specific compatibility varies. Use the format supported by the documented exporter and verify the result in SOMA's tools.

== Prepare the files ==

# Export the model according to [[HPL3/SOMA/Modeling/Modeling Guidelines|Modeling Principles]] and the instructions for the chosen exporter.
# Put the model in its final mod resource directory, normally under <code>static_objects/</code> or <code>entities/</code>.
# Put its textures and <code>.mat</code> files in resource paths available to the mod.
# Confirm the directory is included by <code>resources.cfg</code> before opening the asset in an editor.

For automatic material resolution, assign the diffuse texture in the source model and provide an HPL3 material with the same base name. For example:

<pre>
panel.dae
panel.dds
panel.mat
</pre>

When the model references <code>panel.dds</code>, HPL3 looks for <code>panel.mat</code>. A model with multiple materials must use separate submeshes, each with its own texture/material reference.

== Validate the exported mesh ==

# Start <code>ModelViewer.exe</code> and load the exported model from its final resource location.
# Check that the object has the expected orientation, scale, pivot, submeshes, and materials.
# Inspect the tool output or HPL log for missing mesh, texture, or material messages.
# Close and reopen the asset after correcting the source export so stale state is not mistaken for a successful fix.

Loading a source mesh generates or refreshes its <code>.msh</code> cache. The executable contains an explicit “cache out of date” path that reloads the Collada source. Keep the source model in the mod; do not treat the generated cache as the editable master.

SOMA's shipped files demonstrate this pairing extensively: 5,444 inspected <code>.dae</code> files under <code>static_objects</code> and <code>entities</code> have a same-path <code>.msh</code> cache.

== Import the mesh into an entity ==

# Open <code>ModelEditor.exe</code> and choose '''File → New''' for a new entity.
# Choose '''File → Import Mesh''' and select the exported model.
# Confirm that the expected submeshes appear. Each imported mesh produces one or more submesh objects in the editor.
# Configure materials if a submesh did not resolve the intended <code>.mat</code> automatically.
# Add physics shapes and create bodies where the entity requires collision. Add joints, sub-entities, effects, or animations only as needed.
# Open '''Entity Settings''', choose the appropriate entity type, and configure its type variables.
# Save the entity as an <code>.ent</code> file in the same asset directory.
# Enable '''Entity Preview''' to inspect physics and animations before placing the entity in a map.

A representative shipped entity, <code>entities/urban/utility/air_vent/air_vent.ent</code>, stores this separation directly:

* its <code>Mesh</code> element references <code>air_vent.dae</code>;
* its imported <code>SubMesh</code> is stored under that mesh;
* its collision shape and body are separate sections; and
* its <code>UserDefinedVariables</code> select the <code>StaticProp</code> entity type.

The same directory also contains <code>air_vent.msh</code>. This illustrates the roles of the three files: <code>.dae</code> is the source mesh, <code>.msh</code> is the generated cache, and <code>.ent</code> is the entity setup.

== Reimport an updated mesh ==

When '''Import Mesh''' is used in an entity that already has a mesh, the Model Editor opens the '''SubMesh Reassign''' dialog. This allows saved submesh data to be associated with the new export.

* The left side lists new submeshes and lets each one be paired with an old submesh.
* '''Use new data''' discards the previous submesh parameters for that new submesh.
* The right side lists old submeshes that remain unassigned.
* '''Best Match''' attempts pairing based on triangle count according to the existing editor documentation.

Review every proposed match before accepting it. Stable submesh names and a stable object split make reimport safer; renamed, merged, or divided submeshes require deliberate reassignment. Save the <code>.ent</code> after accepting the mappings and test its bodies, attachments, and animations again.

== Use the result in a map ==

For a static object, select it through the Level Editor's '''Static Object''' mode. For an entity, select the saved <code>.ent</code> through '''Entity EditMode'''. Place one test instance, save and reopen the map, then launch the mod and verify:

* scale and orientation;
* material and texture loading;
* collision and player movement around the object;
* shadows and lighting;
* entity interaction or animation, where applicable.

== Troubleshooting ==

* '''The model cannot be found:''' confirm its folder is included by <code>resources.cfg</code> and that the editor is working on the intended mod.
* '''The model is invisible or malformed:''' verify export scale, up axis, transforms, normals, and triangulation in the source application, then regenerate the cache.
* '''The material is missing:''' confirm that each submesh has a diffuse texture reference and that the corresponding same-base-name <code>.mat</code> can be resolved.
* '''The wrong material appears:''' check for duplicate asset names elsewhere in the resource paths and inspect the submesh's assigned material in Model Editor.
* '''An entity breaks after reimport:''' revisit SubMesh Reassign. A changed skeleton can also make the saved <code>.ent</code> incompatible with the new mesh; SOMA reports this condition as an out-of-date entity/mesh skeleton.
* '''The editor still shows the old model:''' close and reopen the entity or editor after replacing the source and cache; do not assume an in-place resource refresh succeeded.

== See also ==

* [[HPL3/SOMA/Modeling/Modeling Guidelines|Modeling Principles]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Entities/Model Editor View|Model Editor reference]]
* [[HPL3/Entities/Entity Mesh|Submeshes and reassignment]]
* [[HPL3/Entities/Entities Overview|Entity workflow]]

[[Category:English]]

HPL3/SOMA/Modeling/Modeling Guidelines

2026-10-02T15:28:58Z

TiMan: Add practical, source-verified SOMA modeling principles covering asset roles, scale, axes, origin, submeshes, materials, organization, validation, and troubleshooting.

'''Modeling principles''' are the preparation rules that make a 3D asset predictable when it is exported, loaded, textured, and given collision in SOMA. They apply before the asset is configured as a static object or an entity.

== Plan the asset's role ==

Decide how the model will be used before splitting the mesh or building collision:

* A '''static object''' is map geometry intended to remain fixed. Nearby static objects with matching material and render settings can be combined by the engine, so reusable architectural pieces benefit from shared materials.
* An '''entity''' is saved as an <code>.ent</code> file and can contain a mesh, physics shapes and bodies, joints, sub-entities, effects, and animations. Its behavior is selected through an entity type.
* A detailed visible mesh and a practical collision shape need not be identical. Complex or rounded visible geometry often benefits from simpler physics shapes configured in the Model Editor.

Use a static object for fixed scenery unless the object needs entity features such as scripted behavior, articulated physics, animation, or per-instance gameplay variables.

== Scale, axes, and origin ==

* Work at a consistent real-world scale. The SOMA export guide recommends treating one unit as one metre, or using centimetres consistently so a one-metre object is 100 units high. Exported unit metadata may be used by the importer.
* Keep the same unit scale for a rigged mesh and all of its animations. The documented result of a mismatch is an animated mesh that expands or shrinks.
* Configure the source application's up axis deliberately and validate the export in SOMA. Of 5,490 inspected shipped Collada files, 5,207 declare <code>Y_UP</code> and 283 declare <code>Z_UP</code>; the installed assets therefore do not justify treating one declaration as universal.
* Place the origin deliberately. The existing SOMA modeling guide recommends positioning an ordinary prop so its bottom is at the origin. This gives a useful placement point on floors; doors, wheels, and other pivoting objects instead need an origin suited to their intended movement.
* Apply or otherwise account for object transforms before export according to the exporter being used. Validate the result in an HPL3 tool rather than assuming the modeling application's displayed scale is authoritative.

== Geometry and submeshes ==

* Give exported objects and mesh datablocks stable, descriptive names. Submesh names matter when an existing entity is reimported and its saved submesh data must be reassigned.
* Export polygon meshes in a form the selected exporter can reliably convert. The shipped Collada example inspected for this guide records triangle export, and the existing Modo and Blender guidance requires triangulation before export.
* Remove accidental duplicate geometry and unused objects from the export selection.
* Split geometry by material where necessary. HPL3 assigns one material to each submesh; a model needing multiple materials therefore needs multiple submeshes.
* Avoid unnecessary submesh and material splits. For static geometry, nearby objects that share a material and compatible settings can be combined at load time, reducing draw calls.
* Keep collision requirements in mind while modeling. Render geometry that is too detailed for collision can use simpler shapes or a separate collision setup in an <code>.ent</code> file.

== UVs and materials ==

* UV-unwrap every textured submesh and keep the UV layout valid for the texture workflow being used.
* Assign the intended diffuse texture to every exported submesh. The importer uses that texture reference to locate the corresponding HPL3 <code>.mat</code> file.
* Match the diffuse texture and material base names. For example, a submesh using <code>panel.dds</code> should have a material named <code>panel.mat</code> available through the resource paths.
* Use distinct texture/material base names for distinct submesh materials, such as <code>door_frame.dds</code>/<code>door_frame.mat</code> and <code>door_leaf.dds</code>/<code>door_leaf.mat</code>.
* Set each material's physics material deliberately when its surface will provide collision. One <code>.mat</code> file has one physics-material setting.

The older SOMA project guide gives historical recommendations for texture formats, suffixes, and relative sizes. Treat those as project conventions, not as proof that every modern mod asset must use the same compression or dimensions. The material file and the current tool output are the authoritative test.

== Organize files predictably ==

Keep an asset's source model, generated cache, materials, textures, and optional entity file in a stable resource directory. A typical entity asset may look like:

<pre>
entities/my_mod/machine/
├── machine.dae
├── machine.msh
├── machine.ent
├── machine.dds
├── machine_nrm.dds
└── machine.mat
</pre>

The exact texture set depends on the material. Same-basename organization is not an engine requirement for every auxiliary texture, but it makes dependencies easier to identify and matches many shipped SOMA assets. In the installed game, 2,944 entity assets have same-basename <code>.ent</code>, <code>.dae</code>, and <code>.msh</code> files.

Make sure the containing directory is included by the mod's <code>resources.cfg</code>. Do not rely on absolute paths embedded by the modeling application; test the asset from its final mod-relative location.

== Validate in small steps ==

# Export the source mesh into its final resource directory.
# Load it in <code>ModelViewer.exe</code> or import it into <code>ModelEditor.exe</code>.
# Check orientation, dimensions, origin, normals, UVs, and material assignment before adding gameplay setup.
# If it will be an entity, save a minimal <code>.ent</code>, then add shapes, bodies, joints, and type variables incrementally.
# Place the static object or entity in a test map and check it in-game under representative lighting.
# Re-export once and verify that the update workflow preserves the intended submesh assignments.

This staged process separates mesh/export problems from material, physics, entity-type, and map-placement problems.

== Common problems ==

* '''Wrong size:''' verify the source scene units and exported unit metadata. For animated assets, verify the mesh and animation use the same scale.
* '''Wrong orientation or pivot:''' fix the source axes/origin and re-export rather than compensating separately in every map instance.
* '''Missing material:''' confirm that the submesh has a diffuse texture reference and that the matching <code>.mat</code> is reachable through the mod resources.
* '''Only one material appears:''' separate faces that need different materials into different exported submeshes.
* '''Collision is expensive or catches on details:''' use simpler Model Editor shapes or a deliberately simplified collider instead of the full visible mesh.
* '''Reimport loses setup:''' keep stable submesh names and review every mapping in the SubMesh Reassign dialog.

== See also ==

* [[HPL3/SOMA/Modeling/Importing Models|Importing Models]]
* [[HPL3/SOMA/Modeling/Exporting Models|Exporting Models]]
* [[HPL3/Materials/Working with Materials|Working with Materials]]
* [[HPL3/Entities/Entities Overview|Entities Overview]]
* [[HPL3/Blender HPL3 export plugin|Blender HPL3 export plugin]]

[[Category:English]]

HPL3/Areas/MapTransfer Area

2026-10-02T15:18:12Z

TiMan: Resolve the shared MapTransfer redlink to the detailed SOMA-specific streaming guide.

#REDIRECT [[HPL3/SOMA/Areas/MapTransfer Area]]

HPL3/Areas/Sit Area

2026-10-02T15:18:10Z

TiMan: Redirect the generic Sit Area reference to the detailed SOMA-specific runtime guide.

#REDIRECT [[HPL3/SOMA/Areas/Sit Area]]

HPL3/SOMA/Areas/MapTransfer Area

2026-10-02T15:17:40Z

TiMan: Expand the SOMA MapTransfer Area guide with verified streaming behavior, campaign examples, setup, testing, and troubleshooting.

A '''MapTransfer Area''' is a named volume used by SOMA's map-streaming functions to identify the player and objects that should be preserved while the current map is unloaded and the next map is activated.

'''Important:''' A MapTransfer Area does not initiate a map change when the player enters it. SOMA's area script has no interaction or automatic collision behavior. A map script must pass the area's name to the map-deload and map-change functions.

== Create the transfer volume ==

# In the Level Editor, select '''Area EditMode''' and choose <code>MapTransfer</code>.
# Place and scale the volume so it contains the player and every object that must survive the transition at the moment the script runs.
# Give it a clear name. SOMA's campaign commonly names a pair after the adjoining maps, such as <code>Transfer2122</code> for the transition from <code>02_01</code> to <code>02_02</code>.
# Create a matching transfer volume in the adjoining map when following the campaign's paired-area pattern.
# Use that exact name in the transition script.

The SOMA class inherits the common <code>BasicArea</code> properties but adds no MapTransfer-specific editor variables. Its placement, size, orientation, active state, and name therefore define its role.

== Use it from a map script ==

Include the map helper:

<syntaxhighlight lang="cpp">
#include "helpers/helper_map.hps"
</syntaxhighlight>

For a streamed transition, pass the same area name to <code>Map_Deload</code> and the five-argument <code>Map_ChangeMap</code> overload:

<syntaxhighlight lang="cpp">
Map_Deload("Transfer2122");

// Call after the destination has finished preloading.
Map_ChangeMap("02_02_ms_curie_inside.hpm", "", "Transfer2122", "", "");
</syntaxhighlight>

These calls are shortened from SOMA's Curie Outside transition. The shipped script begins preloading first and waits until <code>Map_IsPreloadCompleted()</code> before changing maps. See [[HPL3/SOMA/Scripting/Level Streaming|Level Streaming]] for that complete sequence.

{| class="wikitable"
! Argument !! Role
|-
| <code>Map_Deload(asTransferArea)</code> || Deloads the current map while preserving objects inside the named transfer area.
|-
| <code>Map_ChangeMap(..., asTransferArea, ...)</code> || Passes the named transfer area to the native map-change operation. The helper's source describes this as the area used to transfer objects and the player from one map to another.
|}

Using the four-argument <code>Map_ChangeMap</code> overload supplies an empty transfer-area name, so it performs a normal change rather than this named transfer workflow.

== Shipped SOMA pattern ==

The inspected campaign contains 36 MapTransfer instances with 17 distinct names. Most transition names occur in both adjoining maps. For example, <code>Transfer2122</code> exists in:

* <code>maps/chapter02/02_01_ms_curie_outside/02_01_ms_curie_outside.hpm_Area</code>; and
* <code>maps/chapter02/02_02_ms_curie_inside/02_02_ms_curie_inside.hpm_Area</code>.

The source map calls both <code>Map_Deload("Transfer2122")</code> and <code>Map_ChangeMap(..., "Transfer2122", ...)</code>. Other paired campaign names include <code>Transfer0102</code>, <code>Transfer0203</code>, <code>Transfer2324</code>, and <code>transfer4142</code>.

SOMA also uses a larger <code>PreTransfer0102</code> volume for an earlier partial deload, followed later by <code>Transfer0102</code> for the final transition. This demonstrates that a transfer volume can support staged unloading as well as the final map change.

== Test the transition ==

# Verify that the named volume exists and is active in the source map. SOMA reports an error and does not deload the level if the requested transfer area cannot be found.
# Enter the volume with every object that should survive the transition.
# Trigger the preload/deload/change sequence and wait for the destination map.
# Confirm that the player and intended objects transfer, while unrelated parts of the old map are unloaded.
# Test from a fresh launch and from a save made before the transition.

Some props can explicitly disallow map transfer through <code>SetAllowMapTransfer(false)</code>. If a prop inside the volume does not survive, check its script or interaction state before assuming the area bounds are wrong.

== Troubleshooting ==

* '''Nothing happens on entry:''' this is expected. Add or connect the script that starts preloading and eventually calls <code>Map_ChangeMap</code>.
* '''“Map Transfer Area not found” appears:''' verify the area name in the map and every script call. Use the exact spelling used by the placed object.
* '''Objects disappear during deload:''' confirm they are inside the transfer volume when <code>Map_Deload</code> runs and that they allow map transfer.
* '''The destination loads without the transferred state:''' use the five-argument overload and pass the transfer-area name; the four-argument overload passes an empty name internally.
* '''The transition runs before streaming is ready:''' wait for <code>Map_IsPreloadCompleted()</code>, as in the stock Level Streaming example.

== See also ==

* [[HPL3/SOMA/Scripting/Level Streaming|Level Streaming]]
* [[HPL3/SOMA/Scripting/Map Helper|Map Helper]]
* [[HPL3/SOMA/Areas|SOMA areas]]

[[Category:English]]

HPL3/Areas/Exposure Area

2026-10-02T15:17:39Z

TiMan: Add a source-verified HPL3 Exposure Area guide with editor workflow, properties, shipped examples, scope notes, and troubleshooting.

An '''Exposure Area''' is a box volume that changes camera tone-mapping values while the camera is inside it. It can be used to make the view adapt when moving between regions with substantially different brightness.

Exposure Areas are dedicated Level Editor objects. They are created through '''ExposureArea EditMode''' and are stored in the map's <code><map name>.hpm_ExposureArea</code> track, not as an <code>AreaType</code> in <code>.hpm_Area</code>.

== Create an Exposure Area ==

# In the Level Editor, select '''ExposureArea EditMode'''.
# Set the exposure, white-cut, and transition-time values for the new object.
# Create a box covering the region in which those tone-mapping values should apply.
# Select the object to adjust its position, rotation, size, or effect values.
# Save and test the map while moving the camera across every boundary of the volume.

The edit-mode values apply to newly created Exposure Areas. After placing one, select that object before changing its individual settings.

== Properties ==

{| class="wikitable"
! Property !! Serialized attribute !! Purpose
|-
| '''Name''' || <code>Name</code> || Unique object name within the map.
|-
| '''Position''' || <code>WorldPos</code> || Center of the box in world space.
|-
| '''Rotation''' || <code>Rotation</code> || Rotation of the box volume.
|-
| '''Size''' || <code>Scale</code> || Dimensions of the affected box.
|-
| '''Exposure''' || <code>Exposure</code> || Target tone-mapping exposure. The existing editor reference documents that increasing it makes the image brighter and gives an editor range of <code>-10</code> to <code>10</code>.
|-
| '''White Cut''' || <code>WhiteCut</code> || Target tone-mapping white-cut value. Older documentation calls this setting '''WhitePoint'''; shipped map files and the current editor binary use <code>WhiteCut</code>.
|-
| '''Transition Time''' || <code>TransitionTime</code> || Time used to transition to the area's exposure settings.
|}

== Placement guidance ==

* Cover the entire region that needs the alternate exposure, including the camera's likely path rather than only the player's feet.
* Use a nonzero transition time when an immediate tone-mapping change would be distracting.
* Test both directions across the boundary. A value suitable when entering a dark room may expose an abrupt change when leaving it.
* Avoid unexplained overlap until the intended precedence has been tested. The shipped attributes do not record an editable priority value.
* Judge the result in-game with the final lights, fog, bloom, and color grading active; the numeric value alone does not establish the visual result.

== Shipped examples ==

Six Exposure Areas occur in four inspected SOMA map tracks. Their values demonstrate that settings are scene-specific rather than universal defaults.

{| class="wikitable"
! Map !! Exposure !! WhiteCut !! TransitionTime
|-
| <code>chapter00/00_01_apartment</code> || <code>-1.2</code> || <code>2.2</code> || <code>3</code>
|-
| <code>chapter00/00_03_laboratory</code> || <code>-1</code> || <code>4</code> || <code>2</code> or <code>1.9</code>
|-
| <code>chapter01/01_01_upsilon_awake</code> || <code>1</code> || <code>2.7</code> || <code>3</code>
|}

The laboratory map uses three separate volumes along part of the level, with the same exposure and white-cut targets and closely matched transition times. This is a useful example of applying consistent settings across multiple volumes, not a preset for other lighting conditions.

== Shared HPL3 scope ==

The SOMA, Amnesia: Rebirth, and Amnesia: The Bunker Level Editor executables all contain the <code>ExposureArea</code> object and the <code>Exposure</code>, <code>WhiteCut</code>, and <code>Transition Time</code> controls. SOMA and Rebirth ship map tracks with the same three serialized effect attributes. No shipped Bunker Exposure Area was found, so the Bunker comparison establishes editor support rather than a campaign example.

== Troubleshooting ==

* '''Nothing changes:''' confirm that the camera actually enters the box and that the saved <code>.hpm_ExposureArea</code> track contains the object.
* '''The change is too abrupt:''' increase '''Transition Time''' and retest both entry and exit.
* '''The scene becomes too bright or dark:''' move '''Exposure''' toward the map's surrounding value and evaluate it with the final lighting setup.
* '''The result clips bright parts of the image:''' adjust '''White Cut''' separately from exposure; they are distinct stored values.
* '''The effect disappears after copying a map:''' keep the <code>.hpm_ExposureArea</code> sidecar beside the main <code>.hpm</code> file.

== See also ==

* [[HPL3/Level Design/Exposure Areas|ExposureArea EditMode reference]]
* [[HPL3/SOMA/Level Design/Level Settings|Level-wide tone mapping settings]]
* [[HPL3/SOMA/Areas|SOMA areas]]

[[Category:English]]

HPL3/SOMA/Areas/Sit Area

2026-10-02T15:17:38Z

TiMan: Add a source-verified SOMA Sit Area guide covering placement, properties, runtime behavior, testing, and documented limitations.

A '''Sit Area''' is an interactable SOMA area that moves the player's camera to the area's position and orientation, then limits how far the player can look while seated. It uses SOMA's dedicated <code>State_Sit</code> player state.

== Create and place a Sit Area ==

# In the Level Editor, select '''Area EditMode''' and choose the <code>Sit</code> area type.
# Place the area where the player's camera should end up while seated.
# Rotate its orientation indicator toward the desired forward direction. The Sit state reads the area's complete transform as the target camera transform.
# Set '''MaxYaw''' and '''MaxPitch''' to limit the seated view.
# Give the area a clear unique name, save the map, and test it in development mode.

The class definition enables the orientation indicator and disables ordinary scaling in the editor. Placement and rotation are therefore the important setup operations. Keep the target camera position clear of nearby geometry.

== Properties ==

{| class="wikitable"
! Property !! Type !! Default !! Purpose
|-
| <code>MaxYaw</code> || Float || <code>80</code> || Maximum horizontal view offset from the area's forward direction. The area script converts this editor value from degrees to radians before entering the Sit state.
|-
| <code>MaxPitch</code> || Float || <code>50</code> || Maximum vertical view offset from the area's forward direction. The area script also converts this value from degrees to radians.
|}

== Runtime behavior ==

When the player focuses the area, SOMA displays the sit-down interaction icon. Interacting performs the following sequence:

# The area disables itself so it cannot be selected again during the transition.
# Its yaw limit, pitch limit, and name are passed to <code>State_Sit</code>.
# The player changes to the Sit state.
# Over <code>1.5</code> seconds, the camera interpolates from its original transform to the Sit Area's transform.
# Once seated, normal movement input is suppressed and look input is clamped to the configured yaw and pitch limits.

The player can leave the state with interaction cancel, forward movement, or jump. On a normal exit, the camera returns to ordinary control and the Sit Area is reactivated. While seated, the player can still interact with a focused prop; SOMA preserves the special read crosshair for readable props and otherwise shows the default crosshair.

== Shipped SOMA reference ==

SOMA contains one serialized Sit Area, <code>SitArea_5</code>, in <code>maps/chapter00/00_03_laboratory/00_03_laboratory.hpm_Area</code>. It uses the default values <code>MaxYaw=80</code> and <code>MaxPitch=50</code>, and its rotation faces in the opposite horizontal direction from the default orientation.

That shipped instance is saved with <code>Active="false"</code>. It confirms the serialized type, transform, and properties, but it is not an active campaign demonstration of the complete interaction.

== Test the area ==

# Approach the area and confirm that the sit-down icon appears.
# Interact and confirm that the camera moves to the intended position without clipping into the seat or nearby geometry.
# Look in every direction and verify that the limits fit the scene.
# Press interaction cancel, forward, or jump and confirm that ordinary camera and movement control return.
# Interact again to confirm that the area was reactivated.

== Still to verify ==

SOMA has no active shipped Sit Area to use as a visual reference. Exact placement relative to different chair meshes, collision-clearance requirements, and behavior after save/load should be verified in a test map.

== See also ==

* [[HPL3/SOMA/Areas|SOMA areas]]
* [[HPL3/SOMA/Getting Started/Test Debug and Continue|Test, debug and continue]]

[[Category:English]]

HPL3/SOMA/Areas

2026-10-02T15:09:52Z

TiMan: /* Unused Areas */

HPL3/SOMA/Level Design

2026-10-02T15:08:08Z

TiMan: Repair the Level Design category layout using the equivalent explicit two-column table markup.

'''This category deals with the SOMA Level Editor, Level Design and related topics.'''
{| width="100%" cellspacing="8px" style="background:#404040; border:none 1px solid;"
| rowspan="99" width="50%" style="background:#262626; vertical-align: top; padding:0 1em 1em; border:none;" |

== Getting Started ==
* [[HPL3/SOMA/Level Design/Your First Map|Your First Map]]
* [[HPL3/SOMA/Level Design/Advice for Level Designers|Advice for Level Designers]]

== General ==
* [[HPL3/SOMA/Level Design/Level Editor Controls|Level Editor Controls]]
* [[HPL3/SOMA/Level Design/Level Editor View|Level Editor View]]
* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Level Editor Toolbar]]
* [[HPL3/Level Design/Level Editor Color Dialog|Level Editor Color Dialog]]
* [[HPL3/SOMA/Level Design/Level Editor Preferences|Level Editor Preferences]]
* [[HPL3/SOMA/Level Design/Level Settings|Level Settings]]
* [[HPL3/SOMA/Level Design/Level Information|Level Information]]
* [[HPL3/SOMA/Level Design/Pose Editor|Pose Editor]]
* [[HPL3/SOMA/Level Design/Finding Objects|Finding Objects]]
* [[HPL3/SOMA/Level Design/Importing and Exporting Objects|Importing and Exporting Objects]]
* [[HPL3/SOMA/Level Design/Compounds|Compounds]]

== Primitives ==
* [[HPL3/SOMA/Level Design/Working with Primitives|Working with Primitives]]

== Static Objects ==
* [[HPL3/SOMA/Level Design/Working with Static Objects|Working with Static Objects]]

== Entities ==
* [[HPL3/Level Design/Working with Entities|Working with Entities]]
* [[HPL3/Level Design/Entity Poser|Entity Poser]]
* [[HPL3/Level Design/Detail Mesh Entity|Detail Mesh Entity]]

== Lighting ==
* [[HPL3/Level Design/Lights Overview|Lights Overview]]
* [[HPL3/SOMA/Level Design/Point Lights|Point Lights]]
* [[HPL3/SOMA/Level Design/Spot Lights|Spot Lights]]
* [[HPL3/SOMA/Level Design/Light Masks|Light Masks]]
* [[HPL3/SOMA/Level Design/Global Spot Light|Global Spot Light]]
* [[HPL3/SOMA/Level Design/SH Probes|SH Probes]]

| rowspan="99" width="50%" style="background:#262626; vertical-align: top; padding:0 1em 1em; border:none;" |

== Terrain Editor ==
* [[HPL3/Level Design/Terrain Editor Overview|Terrain Editor Overview]]
* [[HPL3/SOMA/Level Design/Creating Terrain|Creating Terrain]]
* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
* [[HPL3/Level Design/Terrain Painting|Terrain Painting]]
* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
* [[HPL3/Level Design/Undergrowth|Undergrowth]]

== Effects ==
* [[HPL3/Level Design/HDR|HDR]]
* [[HPL3/Color_Grading|Color Grading]]
* [[HPL3/SOMA/Level Design/Environment Particles|Environment Particles]]
* [[HPL3/Level Design/Billboards|Billboards]]
* [[HPL3/Level Design/Lens Flares|Lens Flares]]
* [[HPL3/Level Design/Particles|Particles]]
* [[HPL3/Level Design/Sounds|Sounds]]
* [[HPL3/Level Design/Decals|Decals]]
* [[HPL3/Level Design/Fog Areas|Fog Areas]]
* [[HPL3/Level Design/Exposure Areas|Exposure Areas]]

== Detailing ==
* [[HPL3/SOMA/Level Design/Combos|Combos]]
* [[HPL3/Level Design/Detail Meshes|Detail Meshes]]

== Design Theory ==
* [[HPL3/SOMA/Level Design/Indoor Level Performance|Indoor Level Performance]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Outdoor Level Performance]]

== Resources ==
*[https://docs.google.com/document/d/1fAlf2MwEFTwePwzbP3try1H0aYa9kpVBHPBkyIq-caY/edit In Pursuit of Better Levels] - Free educational book on Level Design
*[[HPL3/Resources/TDD Asset Pack|"Amnesia: The Dark Descent" Asset Pack]]
|}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Level Design

2026-10-02T15:04:26Z

TiMan: Point Creating Terrain directly to the expanded SOMA-specific terrain guide.

'''This category deals with the SOMA Level Editor, Level Design and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/SOMA/Level Design/Your First Map|Your First Map]]
* [[HPL3/SOMA/Level Design/Advice for Level Designers|Advice for Level Designers]]

== General ==
* [[HPL3/SOMA/Level Design/Level Editor Controls|Level Editor Controls]]
* [[HPL3/SOMA/Level Design/Level Editor View|Level Editor View]]
* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Level Editor Toolbar]]
* [[HPL3/Level Design/Level Editor Color Dialog|Level Editor Color Dialog]]
* [[HPL3/SOMA/Level Design/Level Editor Preferences|Level Editor Preferences]]
* [[HPL3/SOMA/Level Design/Level Settings|Level Settings]]
* [[HPL3/SOMA/Level Design/Level Information|Level Information]]
* [[HPL3/SOMA/Level Design/Pose Editor|Pose Editor]]
* [[HPL3/SOMA/Level Design/Finding Objects|Finding Objects]]
* [[HPL3/SOMA/Level Design/Importing and Exporting Objects|Importing and Exporting Objects]]
* [[HPL3/SOMA/Level Design/Compounds|Compounds]]

== Primitives ==
* [[HPL3/SOMA/Level Design/Working with Primitives|Working with Primitives]]

== Static Objects ==
* [[HPL3/SOMA/Level Design/Working with Static Objects|Working with Static Objects]]

== Entities ==
* [[HPL3/Level Design/Working with Entities|Working with Entities]]
* [[HPL3/Level Design/Entity Poser|Entity Poser]]
* [[HPL3/Level Design/Detail Mesh Entity|Detail Mesh Entity]]

== Lighting ==
* [[HPL3/Level Design/Lights Overview|Lights Overview]]
* [[HPL3/SOMA/Level Design/Point Lights|Point Lights]]
* [[HPL3/SOMA/Level Design/Spot Lights|Spot Lights]]
* [[HPL3/SOMA/Level Design/Light Masks|Light Masks]]
* [[HPL3/SOMA/Level Design/Global Spot Light|Global Spot Light]]
* [[HPL3/SOMA/Level Design/SH Probes|SH Probes]]

{{CategoryNewcolumn}}

== Terrain Editor ==
* [[HPL3/Level Design/Terrain Editor Overview|Terrain Editor Overview]]
* [[HPL3/SOMA/Level Design/Creating Terrain|Creating Terrain]]
* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
* [[HPL3/Level Design/Terrain Painting|Terrain Painting]]
* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
* [[HPL3/Level Design/Undergrowth|Undergrowth]]

== Effects ==
* [[HPL3/Level Design/HDR|HDR]]
* [[HPL3/Color_Grading|Color Grading]]
* [[HPL3/SOMA/Level Design/Environment Particles|Environment Particles]]
* [[HPL3/Level Design/Billboards|Billboards]]
* [[HPL3/Level Design/Lens Flares|Lens Flares]]
* [[HPL3/Level Design/Particles|Particles]]
* [[HPL3/Level Design/Sounds|Sounds]]
* [[HPL3/Level Design/Decals|Decals]]
* [[HPL3/Level Design/Fog Areas|Fog Areas]]
* [[HPL3/Level Design/Exposure Areas|Exposure Areas]]

== Detailing ==
* [[HPL3/SOMA/Level Design/Combos|Combos]]
* [[HPL3/Level Design/Detail Meshes|Detail Meshes]]

== Design Theory ==
* [[HPL3/SOMA/Level Design/Indoor Level Performance|Indoor Level Performance]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Outdoor Level Performance]]

== Resources ==
*[https://docs.google.com/document/d/1fAlf2MwEFTwePwzbP3try1H0aYa9kpVBHPBkyIq-caY/edit In Pursuit of Better Levels] - Free educational book on Level Design
*[[HPL3/Resources/TDD Asset Pack|"Amnesia: The Dark Descent" Asset Pack]]
{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/Level Design/Creating Terrain

2026-10-02T15:04:24Z

TiMan: Resolve the terrain-guide redlink to the expanded source-verified SOMA article.

#REDIRECT [[HPL3/SOMA/Level Design/Creating Terrain]]

HPL3/SOMA/Level Design/Creating Terrain

2026-10-02T15:03:58Z

TiMan: Expand the SOMA terrain guide with verified setup fields, creation workflow, shipped-map examples, sidecar files, validation constraints, and troubleshooting.

{{shortPageTitle}}

A '''terrain''' is an editable height-mapped surface created inside the SOMA Level Editor. It is useful for large continuous ground such as a seabed or an outdoor landscape. Terrain has separate tools for shaping its height map, painting materials, adding terrain decals, and placing undergrowth.

{{note|Create terrain in a map inside your mod, not in one of SOMA's original maps. Creating a new terrain cannot be undone and clears the editor's undo history. Save the map before opening the creation dialog.}}

== Before you start ==

# Open your mod's map in <code>LevelEditor.exe</code>. See [[HPL3/SOMA/Getting Started/Edit Your First Map|Edit Your First Map]] if the mod-aware editor and save/reopen workflow have not already been tested.
# Save a backup of the map and all of its adjacent <code>.hpm_*</code> files.
# Select '''Terrain EditMode''' on the Level Editor toolbar.

Every inspected shipped SOMA map has a terrain track named <code><map name>.hpm_Terrain</code>. A shipped map without terrain keeps this track with <code>Active="false"</code>; an active terrain definition records <code>Active="true"</code> and its setup data.

== Create the terrain ==

# In Terrain EditMode, open '''Terrain Setup''' and choose '''Create Terrain'''.
# Set '''HeightMap Size''', '''Unit Size''', '''Max Height''', '''Geometry Patch Size''', and '''Texture Patch Size'''. The dialog also displays the resulting terrain size and texel density.
# Review the warning, then click '''Create'''. Creation cannot be undone and clears the undo stack.
# Save the map before doing detailed sculpting or painting.

The setup values determine the terrain's resolution, scale, vertical range, and patch layout. Choose them before investing time in editing: creating another terrain is a destructive replacement rather than an ordinary undoable edit.

{| class="wikitable"
! Setting !! Purpose and verified constraints
|-
| '''HeightMap Size''' || Sets the stored height-map resolution. SOMA's active shipped terrains use either <code>512</code> or <code>1024</code>. The engine rejects a height map that is smaller than either patch size and rejects a height map whose width and height differ.
|-
| '''Unit Size''' || Controls the terrain's world scale and therefore affects the size and texel-density values shown by the dialog. Nine of the ten inspected active SOMA terrains use <code>1</code>; one uses <code>0.5</code>. The SOMA outdoor-performance guide recommends <code>1</code> or higher for outdoor terrain.
|-
| '''Max Height''' || Sets the terrain's available vertical range. This is project-dependent: shipped values range from <code>15</code> to <code>512</code>, so there is no single campaign-wide value to copy.
|-
| '''Geometry Patch Size''' || Sets the geometry patch size. It must be a power of two and cannot be larger than the height map. Active shipped SOMA terrains use <code>16</code> or <code>32</code>.
|-
| '''Texture Patch Size''' || Sets the texture patch size. It must be a power of two, cannot be smaller than the geometry patch size, and cannot be larger than the height map. Every inspected active SOMA terrain uses the same value for its geometry and texture patch sizes, matching the outdoor-performance guide.
|}

The values above describe shipped SOMA data and executable validation messages; they are not universal presets. A small test terrain can follow the compact <code>05_01_phi_inside</code> example below, but its dimensions and height range still need to fit the intended map.

== Shape the height map ==

Open the '''HeightMap''' terrain submode. It provides three brush types:

* '''Raise/Lower''' adds or subtracts height where the brush is applied.
* '''Flatten''' moves the affected area toward a chosen height.
* '''Smooth''' reduces sharp height changes.

The brush controls exposed by the SOMA editor include '''Inner Radius''', '''Outer Radius''', '''Falloff Exp''', optional brush noise, octave count, and noise frequency. Work from broad forms to small corrections: establish the main silhouette with a large brush, flatten areas that need deliberate level ground, and smooth unwanted spikes last.

The HeightMap tools also provide '''Import''', '''Export''', and '''Generate'''. When importing, use a square, uncompressed source of an appropriate resolution; the engine reports errors for compressed bitmaps and non-square height maps. Keep a copy of an external source image because the map's working terrain height map is saved as a DDS sidecar.

== Give the terrain a material ==

Switch to the terrain's '''Texture''' submode after the surface exists.

# Assign a '''Base material file'''. This covers terrain that has not been painted by a blend-layer material.
# Adjust its '''Tile amount''', '''HM scale''', '''Fade start''', and three-component '''Detail texture amount''' only as required by the material and scene.
# Set '''Specular Power''' for the terrain.
# Add a blend layer if more surface materials are needed. A blend layer contains four material slots; select the target layer and sublayer before painting.
# Assign terrain <code>.mat</code> files to the required slots, then use the '''Add''' and '''Erase''' brushes to edit their coverage.
# Optionally configure up to three detail textures and their fade range. Cliff diffuse/normal textures and undergrowth can be added later when the basic terrain has been verified.

Use materials whose type is suitable for terrain. Material paths and painted masks are separate data: the paths are recorded in <code>.hpm_Terrain</code>, while each saved blend layer has a corresponding DDS mask.

== Save and verify ==

# Save the map, close it, and reopen it in the Level Editor.
# Confirm that the terrain is still active, has the expected dimensions, and retains a visible base material.
# Make one obvious Raise/Lower edit, save and reopen again, and confirm that the shape persists.
# If a blend layer was added, paint a clearly visible test patch and verify that it also persists.
# Launch the mod and inspect the terrain from the player's reachable area. Check collision, slopes, material scale, and the transition between terrain and surrounding meshes.

A saved terrain uses files beside the main <code>.hpm</code> map:

{| class="wikitable"
! File !! Stored content
|-
| <code><map>.hpm_Terrain</code> || Terrain setup, material paths, detail-texture settings, blend-layer definitions, terrain decals, and undergrowth records.
|-
| <code><map>.hpm_Terrain_heightmap.dds</code> || The active terrain's height-map data.
|-
| <code><map>.hpm_Terrain_blendlayer_N.dds</code> || Painted data for blend layer <code>N</code>. There is one such sidecar for each saved blend layer.
|}

Keep these files together when copying, renaming, packaging, or restoring the map. Editing only the main <code>.hpm</code> file does not preserve the terrain.

== Shipped SOMA example ==

The comparatively small terrain in <code>maps/chapter05/05_01_phi_inside/05_01_phi_inside.hpm_Terrain</code> demonstrates a complete active terrain without cliff textures or undergrowth:

{| class="wikitable"
! Setting !! Stock value
|-
| HeightMap Size || <code>512</code>
|-
| Unit Size || <code>1</code>
|-
| Max Height || <code>15</code>
|-
| Geometry / Texture Patch Size || <code>16 / 16</code>
|-
| Base material || <code>textures/terrain/sand/sand_flat.mat</code>
|-
| Blend layers / material slots || <code>1 / 4</code>
|}

Larger outdoor campaign terrains commonly use a height-map size of <code>1024</code> and matching patch sizes of <code>32</code>, but their maximum heights and materials vary substantially. Treat shipped maps as structural examples rather than templates whose numbers should be copied unchanged.

== Troubleshooting ==

* '''The terrain is absent after reopening:''' confirm that <code><map>.hpm_Terrain</code> is writable, remains beside the main map, and contains <code>Active="true"</code>.
* '''The terrain is untextured or uses a fallback:''' check the base terrain material path and ensure the material and all referenced textures are included by the mod's resources configuration.
* '''The editor rejects the patch settings:''' both patch sizes must be powers of two, the texture patch cannot be smaller than the geometry patch, and neither can exceed the height-map size.
* '''An imported height map fails:''' use a square, uncompressed image. Check that its resolution is not below either patch size.
* '''Paint disappears when the map is moved or packaged:''' include every <code>_blendlayer_N.dds</code> file with the map.
* '''The terrain is too expensive:''' begin with [[HPL3/SOMA/Level Design/Outdoor Level Performance#Terrain|the terrain optimization checklist]]. In particular, use matching geometry and texture patch sizes and avoid unnecessarily small unit sizes.

== See also ==

* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
* [[HPL3/Level Design/Undergrowth|Undergrowth]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Outdoor Level Performance]]

[[Category:English]]

Template:Hpl3DocIndex

2026-10-02T15:00:03Z

TiMan:

{{#if:{{{gettingStartedPage|}}}|
<div style="margin:0 auto 1em; padding:1em; max-width:600px; text-align:center; border:1px solid #555; background:#202122; color:#eaecf0;">
<div style="font-size:125%; font-weight:bold;">New to {{{gameName}}} modding?</div>
Follow the Getting Started guide to create, launch, map, and script your first mod.

[[{{{gettingStartedPage}}}|<span style="color:#6ea8fe;">'''Start the {{{gameName}}} Getting Started guide →'''</span>]]
</div>
}}

{| class="wikitable" style="margin:auto;"
|+<p style="margin:1em auto 0; text-align:center; width:400px;">[[File:{{{bannerImage|}}}|250px|link=|{{{gameName}}}]]</p><p style="margin:1em auto 0; text-align:center; width:400px;"></p>
|-
|'''[[HPL3/{{{gameName}}}/Modding|<center>Modding</center>]]'''
|Create, organize and release your {{{gameName}}} mods
|-
|'''[[HPL3/{{{gameName}}}/Tutorials|<center>Tutorials</center>]]'''
|Step-by-step guides on a variety of topics, created by the community
|-
|'''[[HPL3/{{{gameName}}}/Level Design|<center>Level Design</center>]]'''
|Work with the Level Editor and create immersive worlds
|-
|'''[[HPL3/{{{gameName}}}/Areas|<center>Areas</center>]]'''
|Areas are the main Input and Output systems of HPL3, and are the backbone of every level in the game
|-
|'''[[HPL3/{{{gameName}}}/Scripting|<center>Scripting</center>]]'''
|Script levels, program gameplay mechanics and modify the inner workings of the game, using AngelScript
|-
|'''[[HPL3/{{{gameName}}}/Modeling|<center>Modeling</center>]]'''
|Import, export, add and modify 3D models for the game
|-
|'''[[HPL3/{{{gameName}}}/Animation|<center>Animation</center>]]'''
|Export and add animations for your in-game 3D models
|-
|'''[[HPL3/{{{gameName}}}/Entities|<center>Entities</center>]]'''
|Use the Model Editor to create interactive and dynamic objects
|-
|'''[[HPL3/{{{gameName}}}/Materials|<center>Materials</center>]]'''
|Use the Material Editor to combine Textures and Shaders to create materials
|-
|'''[[HPL3/{{{gameName}}}/Particles|<center>Particles</center>]]'''
|Use the Particle Editor to create 3D or 2D Effects like smoke, sparks, blood and fire
|-
|'''[[HPL3/{{{gameName}}}/Sound|<center>Sound</center>]]'''
|Create and configure sound to add a depth and atmosphere to the game
|-
|'''[[HPL3/{{{gameName}}}/Audition|<center>Audition</center>]]'''
|Create and manage voice lines, dialogues, voice effects and lip-sync
|-
|'''[[HPL3/{{{gameName}}}/Shaders|<center>Shaders</center>]]'''
|Learn and modify the graphical building blocks of the game
|-
|'''[[HPL3/{{{gameName}}}/Third Party Tools|<center>Third-Party Tools</center>]]'''
|Useful developer tools, some of which are created by the community
|-
|'''[[HPL3/{{{gameName}}}/Glossary|<center>Glossary</center>]]'''
|Explanations for terms you may encounter
|}

[[Category:Entry pages]]
__NOTOC____NOEDITSECTION__

HPL3/SOMA/Level Design

2026-10-02T12:52:55Z

TiMan:

'''This category deals with the SOMA Level Editor, Level Design and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/SOMA/Level Design/Your First Map|Your First Map]]
* [[HPL3/SOMA/Level Design/Advice for Level Designers|Advice for Level Designers]]

== General ==
* [[HPL3/SOMA/Level Design/Level Editor Controls|Level Editor Controls]]
* [[HPL3/SOMA/Level Design/Level Editor View|Level Editor View]]
* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Level Editor Toolbar]]
* [[HPL3/Level Design/Level Editor Color Dialog|Level Editor Color Dialog]]
* [[HPL3/SOMA/Level Design/Level Editor Preferences|Level Editor Preferences]]
* [[HPL3/SOMA/Level Design/Level Settings|Level Settings]]
* [[HPL3/SOMA/Level Design/Level Information|Level Information]]
* [[HPL3/SOMA/Level Design/Pose Editor|Pose Editor]]
* [[HPL3/SOMA/Level Design/Finding Objects|Finding Objects]]
* [[HPL3/SOMA/Level Design/Importing and Exporting Objects|Importing and Exporting Objects]]
* [[HPL3/SOMA/Level Design/Compounds|Compounds]]

== Primitives ==
* [[HPL3/SOMA/Level Design/Working with Primitives|Working with Primitives]]

== Static Objects ==
* [[HPL3/SOMA/Level Design/Working with Static Objects|Working with Static Objects]]

== Entities ==
* [[HPL3/Level Design/Working with Entities|Working with Entities]]
* [[HPL3/Level Design/Entity Poser|Entity Poser]]
* [[HPL3/Level Design/Detail Mesh Entity|Detail Mesh Entity]]

== Lighting ==
* [[HPL3/Level Design/Lights Overview|Lights Overview]]
* [[HPL3/SOMA/Level Design/Point Lights|Point Lights]]
* [[HPL3/SOMA/Level Design/Spot Lights|Spot Lights]]
* [[HPL3/SOMA/Level Design/Light Masks|Light Masks]]
* [[HPL3/SOMA/Level Design/Global Spot Light|Global Spot Light]]
* [[HPL3/SOMA/Level Design/SH Probes|SH Probes]]

{{CategoryNewcolumn}}

== Terrain Editor ==
* [[HPL3/Level Design/Terrain Editor Overview|Terrain Editor Overview]]
* [[HPL3/Level Design/Creating Terrain|Creating Terrain]]
* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
* [[HPL3/Level Design/Terrain Painting|Terrain Painting]]
* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
* [[HPL3/Level Design/Undergrowth|Undergrowth]]

== Effects ==
* [[HPL3/Level Design/HDR|HDR]]
* [[HPL3/Color_Grading|Color Grading]]
* [[HPL3/SOMA/Level Design/Environment Particles|Environment Particles]]
* [[HPL3/Level Design/Billboards|Billboards]]
* [[HPL3/Level Design/Lens Flares|Lens Flares]]
* [[HPL3/Level Design/Particles|Particles]]
* [[HPL3/Level Design/Sounds|Sounds]]
* [[HPL3/Level Design/Decals|Decals]]
* [[HPL3/Level Design/Fog Areas|Fog Areas]]
* [[HPL3/Level Design/Exposure Areas|Exposure Areas]]

== Detailing ==
* [[HPL3/SOMA/Level Design/Combos|Combos]]
* [[HPL3/Level Design/Detail Meshes|Detail Meshes]]

== Design Theory ==
* [[HPL3/SOMA/Level Design/Indoor Level Performance|Indoor Level Performance]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Outdoor Level Performance]]

== Resources ==
*[https://docs.google.com/document/d/1fAlf2MwEFTwePwzbP3try1H0aYa9kpVBHPBkyIq-caY/edit In Pursuit of Better Levels] - Free educational book on Level Design
*[[HPL3/Resources/TDD Asset Pack|"Amnesia: The Dark Descent" Asset Pack]]
{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

HPL3/SOMA/Level Design

2026-10-02T12:49:57Z

TiMan: Point the three completed Level Design topics directly to their SOMA-specific guides.

{{constructionNotice|This category and its sub-pages are undergoing major editing, as some information in this category and all the sub pages is currently in the process of being formatted or re-written from scratch to achieve a higher standard of formatting, or not everything is yet available. More pages and information will gradually be added.}}

'''This category deals with the SOMA Level Editor, Level Design and related topics.'''
{{CategoryHeader}}
{{CategoryNewcolumn}}

== Getting Started ==
* [[HPL3/SOMA/Level Design/Your First Map|Your First Map]]
* [[HPL3/SOMA/Level Design/Advice for Level Designers|Advice for Level Designers]]

== General ==
* [[HPL3/SOMA/Level Design/Level Editor Controls|Level Editor Controls]]
* [[HPL3/SOMA/Level Design/Level Editor View|Level Editor View]]
* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Level Editor Toolbar]]
* [[HPL3/Level Design/Level Editor Color Dialog|Level Editor Color Dialog]]
* [[HPL3/SOMA/Level Design/Level Editor Preferences|Level Editor Preferences]]
* [[HPL3/SOMA/Level Design/Level Settings|Level Settings]]
* [[HPL3/SOMA/Level Design/Level Information|Level Information]]
* [[HPL3/SOMA/Level Design/Pose Editor|Pose Editor]]
* [[HPL3/SOMA/Level Design/Finding Objects|Finding Objects]]
* [[HPL3/SOMA/Level Design/Importing and Exporting Objects|Importing and Exporting Objects]]
* [[HPL3/SOMA/Level Design/Compounds|Compounds]]

== Primitives ==
* [[HPL3/SOMA/Level Design/Working with Primitives|Working with Primitives]]

== Static Objects ==
* [[HPL3/SOMA/Level Design/Working with Static Objects|Working with Static Objects]]

== Entities ==
* [[HPL3/Level Design/Working with Entities|Working with Entities]]
* [[HPL3/Level Design/Entity Poser|Entity Poser]]
* [[HPL3/Level Design/Detail Mesh Entity|Detail Mesh Entity]]

== Lighting ==
* [[HPL3/Level Design/Lights Overview|Lights Overview]]
* [[HPL3/SOMA/Level Design/Point Lights|Point Lights]]
* [[HPL3/SOMA/Level Design/Spot Lights|Spot Lights]]
* [[HPL3/SOMA/Level Design/Light Masks|Light Masks]]
* [[HPL3/SOMA/Level Design/Global Spot Light|Global Spot Light]]
* [[HPL3/SOMA/Level Design/SH Probes|SH Probes]]

{{CategoryNewcolumn}}

== Terrain Editor ==
* [[HPL3/Level Design/Terrain Editor Overview|Terrain Editor Overview]]
* [[HPL3/Level Design/Creating Terrain|Creating Terrain]]
* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
* [[HPL3/Level Design/Terrain Painting|Terrain Painting]]
* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
* [[HPL3/Level Design/Undergrowth|Undergrowth]]

== Effects ==
* [[HPL3/Level Design/HDR|HDR]]
* [[HPL3/Color_Grading|Color Grading]]
* [[HPL3/SOMA/Level Design/Environment Particles|Environment Particles]]
* [[HPL3/Level Design/Billboards|Billboards]]
* [[HPL3/Level Design/Lens Flares|Lens Flares]]
* [[HPL3/Level Design/Particles|Particles]]
* [[HPL3/Level Design/Sounds|Sounds]]
* [[HPL3/Level Design/Decals|Decals]]
* [[HPL3/Level Design/Fog Areas|Fog Areas]]
* [[HPL3/Level Design/Exposure Areas|Exposure Areas]]

== Detailing ==
* [[HPL3/SOMA/Level Design/Combos|Combos]]
* [[HPL3/Level Design/Detail Meshes|Detail Meshes]]

== Design Theory ==
* [[HPL3/SOMA/Level Design/Indoor Level Performance|Indoor Level Performance]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Outdoor Level Performance]]

== Resources ==
*[https://docs.google.com/document/d/1fAlf2MwEFTwePwzbP3try1H0aYa9kpVBHPBkyIq-caY/edit In Pursuit of Better Levels] - Free educational book on Level Design
*[[HPL3/Resources/TDD Asset Pack|"Amnesia: The Dark Descent" Asset Pack]]
{{CategoryEnd}}

__NOTOC__

[[Category:Entry pages]]
[[Category:English]]

Advice for Level Designers

2026-10-02T12:49:25Z

TiMan: Resolve the Level Design redlink to the expanded source-verified SOMA guide.

#REDIRECT [[HPL3/SOMA/Level Design/Advice for Level Designers]]

HPL3/Level Design/Environment Particles

2026-10-02T12:49:22Z

TiMan: Resolve the Level Design redlink to the expanded source-verified SOMA guide.

#REDIRECT [[HPL3/SOMA/Level Design/Environment Particles]]

HPL3/Level Design/Combos

2026-10-02T12:49:17Z

TiMan: Resolve the Level Design redlink to the expanded source-verified SOMA guide.

#REDIRECT [[HPL3/SOMA/Level Design/Combos]]

HPL3/SOMA/Level Design/Advice for Level Designers

2026-10-02T12:48:26Z

TiMan: Expand the SOMA guide with verified stock examples, practical steps and precise remaining documentation gaps.

{{shortPageTitle}}

{{stub}}

Start with a working map-editing loop, then check how your layout, lights and effects affect rendering. This guide brings together SOMA’s existing editing and performance guidance so you can apply it while building a level.

== Prove that your edits load ==
# Work on the map inside your mod and check the editor title bar for <code>(Working on mod)</code>.
# Move one existing object an obvious distance, save the map, then close and reopen it.
# Launch the mod and confirm the same change appears in-game.
# Continue with one small map or script change at a time. In development mode, use <code>F5</code> to restart the map and <code>F1</code> to inspect '''Show Error List''' or '''Show HPL Log''' when a change fails.

Keep the map’s <code>.hpm</code> file and its <code>.hpm_*</code> tracks together. If an old version appears, the Getting Started guide recommends closing the game and relaunching the mod to rule out cached state.

== Plan indoor rooms around what can be seen ==
Occlusion culling determines which objects are visible from a position in the level. The [[HPL3/SOMA/Level Design/Indoor Level Performance|indoor performance guide]] recommends separating rooms and their object bounds, using doors or other occluders, and avoiding uninterrupted sightlines between rooms. A diagonal or zigzag corridor is one of its examples.

For a troublesome doorway, check these items:
# Inspect whether the door or blockade is an occluder. SOMA’s entity definition exposes <code>IsOccluder</code>, and the performance guide identifies doors and blockades as useful dynamic occluders.
# In the debug menu, select '''Render Only Occluders''' under '''In Depth''' to inspect the geometry used for culling.
# Look for small gaps around the door, walls and floor. The guide’s doorway example shows how geometry leaks can undermine culling.

The same guide cautions that adding many dynamic occluders increases draw calls and queries; the advice is to identify useful blockers rather than enable every entity indiscriminately.

== Check the bounds of shadow-casting lights ==
The indoor performance guide recommends adjusting a spotlight’s radius and field of view so it does not unnecessarily cover objects or neighboring rooms. It also recommends light masks where a light must be kept within a room.

If a light does not need dynamic shadows for gameplay, the guide recommends disabling '''Shadow affects dynamic'''. It also suggests reducing unnecessary shadow-casting lights and using a gobo where that can replace the required shadow pattern. Test flashlight-dependent rooms with the flashlight on, as the guide explicitly requires that when evaluating performance.

== Check the cost of the effect you add ==
* For reflective water, the indoor guide recommends reducing the objects visible in the reflection. It also describes disabling reflections or lowering the material’s <code>ReflectionFadeEnd</code> when the scene needs both water and detail.
* For outdoor terrain, the outdoor guide recommends using terrain for most of the silhouette and meshes for important landmarks and details.
* For distant objects, that guide recommends distance culling for suitable details while keeping gameplay objects, landmarks and important objects such as lamps from being culled.
* For fog culling, the outdoor guide says fully fogged objects beyond Fog End can be culled when silhouettes are not needed. The map helper’s <code>abCulling</code> argument likewise specifies whether fog-hidden objects are rendered.

== Reuse groups deliberately ==
For repeated arrangements, [[HPL3/SOMA/Level Design/Combos|combos]] store a compound for placement in the editor. For static geometry, the [[HPL3/Level Design/Working with Static Objects|static-object guide]] describes automatic combining of nearby objects with matching materials and settings. It advises sharing materials among pieces often used together, while avoiding textures that group unrelated surfaces and raise memory requirements. These are different uses of grouping.

== Still to expand ==
The verified advice here covers map iteration and rendering. A broader guide to gameplay pacing, player guidance, puzzle layout and evaluating playtests still needs topic-specific source material.

== Continue by task ==
* [[HPL3/SOMA/Getting Started/Edit Your First Map|Make and verify a visible map edit]]
* [[HPL3/SOMA/Getting Started/Test Debug and Continue|Use the development loop]]
* [[HPL3/SOMA/Level Design/Indoor Level Performance|Investigate indoor performance]]
* [[HPL3/SOMA/Level Design/Outdoor Level Performance|Investigate outdoor performance]]

[[Category:English]]

HPL3/SOMA/Level Design/Environment Particles

2026-10-02T12:48:21Z

TiMan: Expand the SOMA guide with verified stock examples, practical steps and precise remaining documentation gaps.

{{shortPageTitle}}

{{stub}}

Environment particles add a field of textured particles to a level. SOMA’s underwater maps use them with the shipped <code>waterdust_tiny_3x3.dds</code> texture. The renderer turns the particle faces toward the camera and wraps their positions inside a box, so this is a repeating particle field.

== Find the controls ==
Open '''Level Settings''' and select its '''Env Particles''' tab. '''Active''' toggles the particles, '''Color''' tints them, and '''Brightness''' controls how bright that tint appears.

The SOMA editor also contains controls labelled '''Texture''', '''Box Size''', '''Box Distance''', '''Num Particles''', '''Particle Size''', '''SubDivs''', '''Affected by light''', '''Num of iterations''', '''Gravity Velocity''', '''Wind Velocity''', '''Rotate Velocity''', '''Fade In''' and '''Fade Out'''. The following example gives the authored map values rather than treating them as editor defaults.

== Reproduce the Delta particle settings ==
Use a map inside your own mod, with the working editor/save/launch setup from [[HPL3/SOMA/Getting Started/Edit Your First Map|Edit Your First Map]]. The example below copies only Delta’s environment-particle settings; Delta’s fog, lighting and other map settings are separate.

# Close the mod map in the editor before editing its <code>.hpm</code> file.
# Open your mod’s <code>maps/sample_map/sample_map.hpm</code> in a text editor. Inside <code>GlobalSettings</code>, replace its <code>EnvParticles</code> element with the following element from <code>maps/chapter02/02_03_delta/02_03_delta.hpm</code>.
# Reopen the mod map in <code>LevelEditor.exe</code> and inspect the '''Env Particles''' tab. The texture is populated and the particles are active, whereas the bundled sample map stores an empty texture and <code>Active="false"</code>.

<syntaxhighlight lang="xml">
<EnvParticles
Color="0.898438 0.959534 1 1"
Brightness="0.3"
BoxDistance="0.1"
GravityVelocity="0 0.01 0"
GravitySpeedRandomAmount="0"
WindVelocity="0 0 0"
WindSpeedRandomAmount="0"
WindDirRandomAmount="0"
RotateVelocity="0.005 0.005 0.005"
RotateSpeedRandomAmount="1"
RotateBothDirs="true"
NumIterations="2"
FadeInStart="0.1"
FadeInEnd="1"
FadeOutStart="10"
FadeOutEnd="16"
BoxSize="10"
NumParticles="3000"
ParticleSize="0.08 0.08"
SubDivUV="3 3"
AffectedByLight="false"
Texture="particles/underwater/materials/waterdust_tiny_3x3.dds"
Active="true"
/>
</syntaxhighlight>

# Save the mod map and launch it. The particle field uses the small underwater-dust texture and the pale blue tint from the copied settings.
# Make one visible comparison in the '''Env Particles''' tab: turn '''Active''' off, save, and restart the map; then turn it on again and repeat. This checks the particle layer separately from fog and other effects. Use [[HPL3/SOMA/Getting Started/Test Debug and Continue|the development loop]] for restarting and reading errors.

== Read the example ==
* <code>Texture</code> references a shipped texture under <code>particles/underwater/materials/</code>; it is a texture filename, not a <code>.ps</code> particle-system file.
* <code>NumParticles="3000"</code>, <code>ParticleSize="0.08 0.08"</code> and <code>SubDivUV="3 3"</code> are Delta’s authored values. They are not a recommended count or a universal preset.
* <code>GravityVelocity="0 0.01 0"</code>, <code>WindVelocity="0 0 0"</code> and <code>RotateVelocity="0.005 0.005 0.005"</code> are distinct motion parameters. The script API has separate setters for all three.
* The fade-in begins at distance <code>0.1</code> and finishes at <code>1</code>; fade-out begins at <code>10</code> and finishes at <code>16</code>. These are distance thresholds, not durations. The map helpers document their meaning, and the rendering shader computes their effect from particle depth.

== Let a script change the field ==
Map scripts can change the particle field after the map loads. Include <code>helpers/helper_map.hps</code> alongside your existing map-script includes. The Delta map enables the field with:

<syntaxhighlight lang="cpp">
Map_SetEnvironmentParticlesActive(true);
</syntaxhighlight>

During its transition towards Theta Outside, the same stock script fades all matching particle layers to a new color and brightness:

<syntaxhighlight lang="cpp">
Map_FadeEnvironmentParticleColor("*", cColor(0.295,0.556,0.59,1.0), 7);
Map_FadeEnvironmentParticleBrightness("*", 1, 7);
</syntaxhighlight>

Here <code>"*"</code> selects all particle layers. The last argument is the fade duration; the Map Effects Handler accumulates elapsed update time for these fades. These calls alter existing layers rather than define their texture, particle count or box size.

== If the particles disappear ==
* Check both the saved <code>Active</code> value and map-script calls: stock SOMA scripts can enable or disable the field at runtime.
* Check that the texture exists; the worked example uses <code>particles/underwater/materials/waterdust_tiny_3x3.dds</code>.
* Check the fade distances. A particle at the fully faded-out distance contributes no visible alpha.
* Check clipping when using water areas. The Liquid area definition exposes <code>EnvParticlesToClip</code> for naming the layers constrained to that area, and accepts wildcards and space-separated names.

== Still to expand ==
The exact units and ranges for the motion and randomization controls, the meaning of Box Distance and iteration count, and a visually verified editor demonstration still need documentation. The stock values above establish an authored setup, not those undocumented semantics.

== See also ==
* [[HPL3/Level Design/Level Settings|Level Settings]]
* [[HPL3/SOMA/Scripting/Map Helper|Map scripting helpers]]
* [[HPL3/SOMA/Scripting/Map Effects Handler|Fading level effects]]

[[Category:English]]

HPL3/SOMA/Level Design/Combos

2026-10-02T12:48:15Z

TiMan: Expand the SOMA guide with verified stock examples, practical steps and precise remaining documentation gaps.

{{shortPageTitle}}

{{stub}}

A combo is a saved compound: an arrangement of objects that can be placed again through the SOMA Level Editor’s Combo EditMode. Use it when you want to reuse a group of pieces rather than assemble each member separately.

== Understand the three kinds of grouping ==
* A '''compound''' groups objects so they can be transformed together in the editor.
* A '''combo''' stores a compound in a <code>.cmb</code> file for placement through Combo EditMode.
* '''Combine EditMode''' groups static geometry for loading as a whole; the toolbar documentation describes this as an optimization feature. This is a separate toolbar mode from placing saved combos.

== Start with a shipped example ==
# Open your mod’s map in <code>LevelEditor.exe</code>; see [[HPL3/SOMA/Getting Started/Edit Your First Map|Edit Your First Map]] for the working-mod setup and save/reopen check.
# Select '''Combo EditMode''' on the toolbar. It is the mode documented for placing saved compounds.
# Use <code>combos/urban/tech/alarm_clock.cmb</code> as the small reference combo. It contains <code>alarm_clock_1</code> and <code>alarm_clock_button_1</code>, each referencing its own <code>.ent</code> file.
# After placing the combo, compare its members with that file’s <code>Components</code> and <code>Compound</code> sections. The compound records both member IDs; it is a group containing two entities.
# Move the compound with its '''Position''' property, then save and reopen the mod map. Compound position, rotation and scale transform the group together.

The alarm-clock combo uses <code>entities/urban/tech/alarm_clock/alarm_clock.ent</code> and <code>entities/urban/tech/alarm_clock/alarm_clock_button.ent</code>. A larger example, <code>combos/urban/furniture/desk_work.cmb</code>, contains one desk and three drawer entities. The vegetation example <code>combos/organic/vegetation_clusters/vegetation_cluster01.cmb</code> contains both static objects and an entity. These are examples of the contents a shipped combo can store.

== Compound transforms ==
{| class="wikitable"
! Property !! What it changes
|-
| '''Name''' || The name of the compound.
|-
| '''Position''' || The compound’s center position.
|-
| '''Rotation''' || The rotation of the group; a member that cannot rotate can restrict this.
|-
| '''Scale''' || The scale of the group; a member that cannot scale can restrict this.
|}

== Saving your own combo ==
The shipped editor includes controls labelled '''Create Compound''', '''Save as Combo''' and '''Destroy Compound'''. The saved examples use the <code>.cmb</code> extension and contain <code>FileIndices</code>, <code>Components</code>, <code>Compound</code> and <code>Thumbnail</code> sections.

The exact save dialog, destination selection, browser refresh procedure and behavior when an existing combo file changes still need direct editor verification. This page therefore does not prescribe an unverified save-and-refresh sequence.

== See also ==
* [[HPL3/SOMA/Level Design/Compounds|Compound objects]]
* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Editor modes]]
* [[HPL3/Level Design/Working with Static Objects|Static geometry and automatic combining]]

[[Category:English]]

HPL3/SOMA/Scripting/Highlight Effect Handler

2026-10-02T12:32:16Z

TiMan: Expand the practical source walkthrough and clarify how to use the handler.

{{shortPageTitle}}

The Highlight Effect Handler briefly sweeps a glow across eligible nearby objects. It scans active physics bodies, checks selected script classes and calls each entity’s _Global_CanBeHighlighted function. The response must supply a Boolean result and the entity ID in global argument 0. On-screen visibility and a minimum light level are also checked.

The stock tool script reads the HighlightActive instance variable. Its _Global_CanBeHighlighted returns that flag and supplies mBaseObj.GetID(); disabling that flag prevents this tool from being accepted by the handler.

== Trace a tool’s highlight setting ==
# Find <code>HighlightActive</code> in <code>editor/userclasses/EntityClasses.def</code>. The tool instance variable is a Boolean with a declared default of true; its description says it controls the highlight effect when the tool is looked at.
# Open <code>script/props/Prop_Tool.hps</code>. The tool reads that instance variable into <code>mbHighlightActive</code> and returns it through the callback below.
# Follow <code>UpdateAddObjects</code> in <code>script/modules/HighlightEffectHandler.hps</code>. It filters for selected stock script classes, requires a mesh and an on-screen entity, and skips entities whose measured light level is below <code>0.1</code>. A true tool flag therefore supplies eligibility; the handler still applies those additional checks.

== Stock tool eligibility callback ==
<syntaxhighlight lang="cpp">
void _Global_CanBeHighlighted()
{
cScript_SetGlobalReturnBool(mbHighlightActive);
cScript_SetGlobalArgID(0,mBaseObj.GetID());
}
</syntaxhighlight>

== See also ==
* [[HPL3/Scripting/User Modules Overview|User modules]]
* [[HPL3/SOMA/Scripting/Modules Helper|SOMA module helpers]]

[[Category:English]]