HPL3/Entities/Working with Physics Bodies

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:

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

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

1. Create and position one or more collision shapes around the model.
2. Select the shape or shapes that should behave as one unit.
3. Press Create Body. Multiple selected shapes produce one body containing multiple shape references.
4. Select the new body and give it a clear, unique name.
5. Set its material, mass, damping, speed limits, and collision flags.
6. Attach only the meshes, bones, lights, sounds, particle systems, or other supported components that should follow that body.
7. 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:

Editor property	Stored attribute	Role
Body Material	Material	Selects the physics/surface material name.
Mass	Mass	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	AngularDamping / LinearDamping	Reduce rotational and translational motion over time.
Max Angular Speed / Max Linear Speed	MaxAngularSpeed / MaxLinearSpeed	Limit rotational and translational speed.
Buoyancy density mul	BuoyancyDensityMul	Multiplies the body's buoyancy-density value.
Blocks sound / Blocks light	BlocksSound / BlocksLight	Control whether the body participates in sound or light blocking.
Continuous collision	ContinuousCollision	Enables continuous-collision handling for the body.
Can attach character / Pushed by character gravity	CanAttachCharacter / PushedByCharacterGravity	Control character interaction with the body.
Collide character / Collide non character	CollideCharacter / CollideNonCharacter	Select the broad collision groups the body responds to.
Volatile	Volatile	Marks the body with the engine's volatile-body flag.
Use surface effects	UseSurfaceEffects	Enables effects associated with the selected surface material.
Has gravity	HasGravity	Controls whether gravity is applied.

Amnesia: Rebirth entities may additionally serialize Active and Tag 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 ModelEditor.log and the game log for material-loading errors.

See also

• Working with Shapes
• Physics Body Properties
• Working with Joints