Frictional Wiki - Recent changes [en]

HPL3/SOMA/Entities/Working with Physics Bodies

TiMan — Fri, 02 Oct 2026 17:34:36 GMT

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

New page

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

HPL3/SOMA/Entities/Entity Notes

TiMan — Fri, 02 Oct 2026 17:34:35 GMT

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

HPL3/SOMA/Entities/Model Editor Preferences

TiMan — Fri, 02 Oct 2026 17:34:33 GMT

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

New page

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

HPL3/SOMA/Entities/Model Editor Controls

TiMan — Fri, 02 Oct 2026 17:34:32 GMT

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

New page

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

HPL3/Entities/Working with Physics Bodies

TiMan — Fri, 02 Oct 2026 17:34:22 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:34:21 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:34:19 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:34:18 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:25:21 GMT

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..."

New page

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

TiMan — Fri, 02 Oct 2026 17:24:54 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:21:10 GMT

HPL3/SOMA/Animation/Exporting Animations

TiMan — Fri, 02 Oct 2026 17:17:40 GMT

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

New page

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

HPL3/SOMA/Animation/Importing Animations

TiMan — Fri, 02 Oct 2026 17:17:39 GMT

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

New page

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

HPL3/SOMA/Modeling/Exporting Animations

TiMan — Fri, 02 Oct 2026 17:16:50 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:16:49 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:16:47 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:14:52 GMT

Modding

HPL3/Amnesia: The Bunker/Modding

TiMan — Fri, 02 Oct 2026 17:11:33 GMT

HPL3/Amnesia: The Bunker/Modding

TiMan — Fri, 02 Oct 2026 17:09:28 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 17:08:10 GMT

Tools

HPL3/SOMA/Areas

TiMan — Fri, 02 Oct 2026 15:31:57 GMT

HPL3/SOMA/Modeling

TiMan — Fri, 02 Oct 2026 15:31:48 GMT

HPL3/SOMA/Modeling/Modeling Guidelines

TiMan — Fri, 02 Oct 2026 15:31:04 GMT

Scale, axes, and origin

HPL3/SOMA/Modeling/Modeling Principles

TiMan — Fri, 02 Oct 2026 15:29:26 GMT

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

New page

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

HPL3/SOMA/Modeling/Importing Models

TiMan — Fri, 02 Oct 2026 15:28:59 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 15:28:58 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 15:18:12 GMT

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

New page

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

HPL3/Areas/Sit Area

TiMan — Fri, 02 Oct 2026 15:18:10 GMT

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

HPL3/SOMA/Areas/MapTransfer Area

TiMan — Fri, 02 Oct 2026 15:17:40 GMT

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

HPL3/Areas/Exposure Area

TiMan — Fri, 02 Oct 2026 15:17:39 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 15:17:38 GMT

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

New page

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

TiMan — Fri, 02 Oct 2026 15:09:52 GMT

Unused Areas

HPL3/SOMA/Level Design

TiMan — Fri, 02 Oct 2026 15:08:08 GMT

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

HPL3/Level Design/Creating Terrain

TiMan — Fri, 02 Oct 2026 15:04:24 GMT

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

New page

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

HPL3/SOMA/Level Design/Creating Terrain

TiMan — Fri, 02 Oct 2026 15:03:58 GMT

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

Template:Hpl3DocIndex

TiMan — Fri, 02 Oct 2026 15:00:03 GMT

HPL3/SOMA/Level Design

TiMan — Fri, 02 Oct 2026 12:52:55 GMT

Advice for Level Designers

TiMan — Fri, 02 Oct 2026 12:49:25 GMT

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

New page

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

HPL3/Level Design/Environment Particles

TiMan — Fri, 02 Oct 2026 12:49:22 GMT

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

New page

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

HPL3/Level Design/Combos

TiMan — Fri, 02 Oct 2026 12:49:17 GMT

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

New page

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

HPL3/SOMA/Level Design/Advice for Level Designers

TiMan — Fri, 02 Oct 2026 12:48:26 GMT

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

HPL3/SOMA/Level Design/Environment Particles

TiMan — Fri, 02 Oct 2026 12:48:21 GMT

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

HPL3/SOMA/Level Design/Combos

TiMan — Fri, 02 Oct 2026 12:48:15 GMT

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

HPL3/SOMA/Scripting/Highlight Effect Handler

TiMan — Fri, 02 Oct 2026 12:32:16 GMT

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

← Older revision		Revision as of 17:34, 2 October 2026
Line 1:		Line 1:
−	= Entity Notes ~~window =~~	+	#REDIRECT [[HPL3/Entities/Entity Notes]]
−
−	~~[[File:window_entitynotes.png~~]]
−
−	~~With this window, one can add small bits of information that will be readable when placing an entity of the currently edited type in LevelEditor, via its Entity Notes dialog.~~
−
−	~~To create a note, just type it in the textbox and close the popup.~~

← Older revision		Revision as of 17:21, 2 October 2026
Line 1:		Line 1:
−	{{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 3D animation in SOMA.'''		'''This category deals with 3D animation in SOMA.'''

@@ Line 7: / Line 7: @@
 == Modding ==
 * [[HPL3/Amnesia: Rebirth/Tutorials/FAQ|FAQ]]
 * [[HPL3/Amnesia: Rebirth/Tutorials/Custom Menu| Custom Menu]]
@@ Line 13: / Line 12: @@
 == Gameplay ==
 == Systems ==
@@ Line 24: / Line 20: @@
 == Agents ==
-* [[HPL3/Amnesia:_Rebirth/Tutorials/Ghouls| Basic Ghoul Setup]]
+* [[HPL3/Amnesia:_The_Bunker/Tutorials/Stalker| Stalker Setup]]
 == 3D ==

@@ Line 19: / Line 19: @@
 * [[Autodesk Maya]]
 * [[Blender]]
-* [[HPL3 Blender Exporting Tool]]
+* [[HPL3/Blender_HPL3_export_plugin|HPL3 Blender Exporting Tool]]
 {{CategoryEnd}}

← Older revision		Revision as of 15:31, 2 October 2026
Line 1:		Line 1:
−	{{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 covers everything about the Area in the HPL3 Engine and SOMA.'''		'''This category covers everything about the Area in the HPL3 Engine and SOMA.'''

@@ Line 1: / Line 1: @@
-'''This category deals with creating, managing and releasing Amnesia: Rebirth mods, including managing and organizing a team.'''
+'''This category deals with creating, managing and releasing Amnesia: The Bunker mods, including managing and organizing a team.'''
 {{CategoryHeader}}
 {{CategoryNewcolumn}}
@@ Line 9: / Line 9: @@
 == Getting Started ==
-* [[HPL3/Amnesia: Rebirth/Modding/Creating a Mod|Creating a Mod]]
+* [[HPL3/Amnesia: The Bunker/Modding/Creating a Mod|Creating a Mod]]
-* [[HPL3/Amnesia: Rebirth/Modding/Setup Modding Environment|Setup Modding Environment]]
+* [[HPL3/Amnesia: The Bunker/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: The Bunker/Developer Commands|Developer Commands]]
-* [[HPL3/Amnesia: Rebirth/Modding/Developer Debug Menu|Developer Debug Menu]]
+* [[HPL3/Amnesia: The Bunker/Modding/Developer Debug Menu|Developer Debug Menu]]
 * [[Mod Content Usage|Mod Content Usage]]
@@ Line 33: / Line 33: @@
 == Resources ==
-*[[HPL3/Amnesia: Rebirth/Modding/MinimalCustomMapMod|Minimal Custom Map Mod]]
+*[[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]]
+*[[HPL3/Amnesia: Rebirth/Third_Party_Tools/Amnesia: Rebirth Mod Manager|Amnesia: The Bunker Mod Manager]]
 {{CategoryEnd}}

@@ Line 15: / Line 15: @@
 * 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.
+* 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.

← Older revision		Revision as of 15:18, 2 October 2026
Line 1:		Line 1:
−	~~{{shortPageTitle}}~~	+	#REDIRECT [[HPL3/SOMA/Areas/Sit Area]]
−	~~{{stub}}~~
−
−	~~<code>Sit</code> is an area class defined in <code>editor/userclasses/AreaClasses.def</code> in SOMA, Amnesia: Rebirth and Amnesia: The Bunker.~~
−
−	~~== Class variables ==~~
−	~~The following table records the shared class variables and their definition defaults. Descriptions are taken from the class definitions.~~
−
−	~~{\| class="wikitable"~~
−	~~! Variable !! Type !! Definition default !! Description~~
−	\|-
−	~~\| <code>MaxYaw</code> \|\| <code>Float</code> \|\| <code>80</code> \|\| Maximum yaw offset from center.~~
−	\|-
−	~~\| <code>MaxPitch</code> \|\| <code>Float</code> \|\| <code>50</code> \|\| Maximum pitch offset from center.~~
−	\|}
−
−	~~== See also ==~~
−	* [[HPL3/SOMA/Areas~~\|SOMA areas]]~~
−
−	~~== Documentation to expand ==~~
−	~~Creation workflow, runtime behavior and a worked map example need expansion.~~
−
−	~~[[Category:English~~]]

@@ Line 1: / Line 1: @@
-{{shortPageTitle}}
+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.
-<code>MapTransfer</code> is an area class defined in <code>editor/userclasses/AreaClasses.def</code> in SOMA.
+'''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.
-The <code>MapTransfer</code> class has no variables of its own in the SOMA definition.
+== Create the transfer volume ==
 == See also ==
 * [[HPL3/SOMA/Areas|SOMA areas]]
 [[Category:English]]

@@ Line 53: / Line 53: @@
 * [[HPL3/SOMA/Areas/DatamineAudioSource Area|DatamineAudioSource Area]]
 * [[HPL3/SOMA/Areas/DatamineAnimNode Area|DatamineAnimNode Area]]
-* [[HPL3/SOMA/Areas/PosNode|PosNode]]
 {{CategoryEnd}}

@@ Line 1: / Line 1: @@
 '''This category deals with the SOMA Level Editor, Level Design and related topics.'''
-{{CategoryHeader}}
+{| width="100%" cellspacing="8px" style="background:#404040; border:none 1px solid;"
-{{CategoryNewcolumn}}
+| rowspan="99" width="50%" style="background:#262626; vertical-align: top; padding:0 1em 1em; border:none;" |
 == Getting Started ==
@@ Line 39: / Line 39: @@
 * [[HPL3/SOMA/Level Design/SH Probes|SH Probes]]
-{{CategoryNewcolumn}}
+| 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/Level Design/Creating Terrain|Creating Terrain]]
+* [[HPL3/SOMA/Level Design/Creating Terrain|Creating Terrain]]
 * [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
 * [[HPL3/Level Design/Terrain Painting|Terrain Painting]]
@@ Line 72: / Line 72: @@
 *[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__

@@ Line 1: / Line 1: @@
 {{shortPageTitle}}
-The SOMA Level Editor toolbar documentation includes Terrain EditMode for creating and configuring terrain.
+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.
-HeightMap mode provides Raise/Lower, Flatten and Smooth brushes. The existing terrain documentation also describes terrain generation and heightmap import/export.
+{{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.}}
 == See also ==
-== Documentation to expand ==
+* [[HPL3/Level Design/Terrain Height Map|Terrain Height Map]]
-The complete terrain-creation dialog, required parameters and first-success procedure need verified documentation.
+* [[HPL3/Level Design/Terrain Texturing|Terrain Texturing]]
 [[Category:English]]

@@ Line 47: / Line 47: @@
 |'''[[HPL3/{{{gameName}}}/Audition|<center>Audition</center>]]'''
 |Create and manage voice lines, dialogues, voice effects and lip-sync
 |-
 |'''[[HPL3/{{{gameName}}}/Third Party Tools|<center>Third-Party Tools</center>]]'''

@@ Line 1: / Line 1: @@
 '''This category deals with the SOMA Level Editor, Level Design and related topics.'''
 {{CategoryHeader}}
@@ Line 7: / Line 5: @@
 == Getting Started ==
 * [[HPL3/SOMA/Level Design/Your First Map|Your First Map]]
-* [[Advice for Level Designers|Advice for Level Designers]]
+* [[HPL3/SOMA/Level Design/Advice for Level Designers|Advice for Level Designers]]
 == General ==
@@ Line 54: / Line 52: @@
 * [[HPL3/Level Design/HDR|HDR]]
 * [[HPL3/Color_Grading|Color Grading]]
-* [[HPL3/Level Design/Environment Particles|Environment Particles]]
+* [[HPL3/SOMA/Level Design/Environment Particles|Environment Particles]]
 * [[HPL3/Level Design/Billboards|Billboards]]
 * [[HPL3/Level Design/Lens Flares|Lens Flares]]
@@ Line 64: / Line 62: @@
 == Detailing ==
-* [[HPL3/Level Design/Combos|Combos]]
+* [[HPL3/SOMA/Level Design/Combos|Combos]]
 * [[HPL3/Level Design/Detail Meshes|Detail Meshes]]

@@ Line 1: / Line 1: @@
 {{shortPageTitle}}
 {{stub}}
-The existing SOMA performance guides discuss occlusion culling and shadow-casting lights for indoor levels, and terrain, fog, distance culling and directional-light shadows for outdoor levels.
+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.
-== See also ==
+== Still to expand ==
-* [[HPL3/SOMA/Getting Started/Edit Your First Map|First visible map edit]]
+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.
-== Documentation to expand ==
+== Continue by task ==
-Gameplay layout, player guidance and playtesting advice need additional sourced documentation.
+* [[HPL3/SOMA/Getting Started/Edit Your First Map|Make and verify a visible map edit]]
 [[Category:English]]

@@ Line 1: / Line 1: @@
 {{shortPageTitle}}
 {{stub}}
-The <code>EnvParticles</code> element in SOMA’s <code>maps/chapter00/00_01_apartment/00_01_apartment.hpm</code> records the following level settings.
+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.
-== Serialized SOMA example ==
+During its transition towards Theta Outside, the same stock script fades all matching particle layers to a new color and brightness:
-== Editor documentation ==
+<syntaxhighlight lang="cpp">
-The documented Env Particles tab contains Active, Color and Brightness controls.
+Map_FadeEnvironmentParticleColor("*", cColor(0.295,0.556,0.59,1.0), 7);
 == See also ==
-* [[HPL3/Level Design/Level Settings|Level settings]]
+* [[HPL3/Level Design/Level Settings|Level Settings]]
+* [[HPL3/SOMA/Scripting/Map Helper|Map scripting helpers]]
-== Documentation to expand ==
+* [[HPL3/SOMA/Scripting/Map Effects Handler|Fading level effects]]
 [[Category:English]]

@@ Line 1: / Line 1: @@
 {{shortPageTitle}}
 {{stub}}
-The SOMA Level Editor toolbar documentation describes Combo EditMode as the mode for placing compound objects saved as combos.
+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.
-Compound objects group simple objects so they can be transformed together. The documented compound properties are Name, Position, Rotation and Scale.
+== Compound transforms ==
-Compound rotation or scaling can be restricted when the group includes an object that cannot be rotated or scaled.
+== Saving your own combo ==
 == See also ==
 * [[HPL3/SOMA/Level Design/Compounds|Compound objects]]
+* [[HPL3/SOMA/Level Design/Level Editor Toolbar|Editor modes]]
-== Documentation to expand ==
+* [[HPL3/Level Design/Working with Static Objects|Static geometry and automatic combining]]
 [[Category:English]]

← Older revision		Revision as of 12:32, 2 October 2026
Line 4:		Line 4:

	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.		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 ==		== Stock tool eligibility callback ==