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

2026-10-02T17:34:22Z

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/Working with Physics Bodies - Revision history

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