Introduction

Props that fall, roll, smash and get knocked about move by a physics system in the level's WORLD/PHYSICS.HKX. A system holds one or more rigid bodies, each with a shape and the values the physics engine moves it by: its mass, friction, bounciness and so on. A PhysicsSystem entity in the prop's composite names its system through its Dynamic Physics System resource.

After loading a level, open View โ†’ Physics System Editor to browse the level's systems, look at their bodies, change a body's values, and import new systems from a mesh, as shown below.

The Physics System Editor on Torrens with system 92, BOTTLE_SPIRIT_01_TEMPLATE, selected: the system list on the left, the preview on the right drawing the bottle's shapes in blue, and under it the body list with Bottle_Spirit_01 (a ListShape, Dynamic (box), mass 1.5) selected above Break_01 to Break_10, the detail line reading MassInv=0.6667, InertiaInv, Friction=0.5, Restitution=0.1, Gravity=1, and the Edit Body... button at the bottom right.

A spirit bottle's system on Torrens: one body for the whole bottle and thirteen for the pieces it breaks into.

The same window opens as a picker from a PhysicsSystem entity's Resources button in the entity inspector, by clicking Set Physics... in its Dynamic Physics System group. As a picker it's titled Select Physics System and has a Select System button (see Assigning a System).

Systems & Bodies

The list on the left has one row per system: its Index (the number a Dynamic Physics System resource stores), its Name, and the full Path that name ends. Retail systems are named after the composite they belong to. Type in Filter: to narrow the list by index or name.

Select a system to draw all of its bodies' shapes in the Preview (drag to orbit, scroll to zoom), with a count of bodies, triangles and shapes underneath. Its bodies are listed below the preview:

  • Body: the body's name. Retail names a body after the ModelReference it moves.
  • Shape: the Havok shape it collides as. Most are a ConvexVerticesShape, a convex hull; a ListShape groups several.
  • Motion: Dynamic bodies are moved by physics (the box or sphere says how its spin is worked out); Keyframed and Fixed bodies are moved by the game, or not at all, and have no mass.
  • Mass: in kilograms, โˆž for a body with no mass.
  • Filter: the body's collision filter, which decides what it collides with.
  • Radius: the radius of a sphere around the body, in metres.
  • LinDamp: its linear damping (see below).

Selecting a body shows the rest of its values on the line under the list: its inverse mass and inverse inertia (what the engine actually stores), friction, restitution, gravity factor, and where it sits in the file.

A system belongs to its prop's composite, so every copy of that prop placed in the level uses the same one: change a body and every copy changes with it.

Editing a Body

Select a body and click Edit Body..., or double-click its row, to change its values:

The Edit Rigid Body dialog for Bottle_Spirit_01, Dynamic (box): a note that a new mass keeps the body's shape and its inertia scales with it, then Mass (kg) 1.500, Friction 0.50, Restitution 0.10, Linear damping 0.000, Angular damping 0.050 and Gravity factor 1.00, with Apply and Cancel buttons.

Editing the whole bottle's body. The boxes open on its current values.

  • Mass (kg): how heavy it is, from 0.001 to 100,000. A heavier body is harder to push and hits harder. The body keeps its shape: its resistance to spinning scales with the new mass. A Keyframed or Fixed body has no mass to change, so the box is greyed out.
  • Friction: how much it grips what it slides on. 0 slides like ice; most retail props use around 0.5, and some go much higher.
  • Restitution: how bouncy it is, from 0 (no bounce) to 1 (bounces back as hard as it hit).
  • Linear damping and Angular damping: how quickly its movement and spin die away on their own, from 0 (they don't) to 1,000.
  • Gravity factor: how strongly gravity pulls it. 1 is normal, 0 floats, and a negative value rises.

Apply writes only the values you changed, then lists the body again with its new values and says it goes into the physics files when the level is next saved. Damping and gravity factor are stored at reduced precision, to about three significant figures, so they may come back very slightly rounded.

A body's values can only be edited on a PC level for now. A mobile or Switch level stores its physics in a different format, and the editor says so if you try.

Importing a System

As in the Collision Editor, two buttons under the list make a new system from a mesh: Import Mesh... for a model file, and From Model... for a model the level already has. Opened from Set Physics..., From Model... starts on the model the composite already draws.

A physics body is convex, so the mesh becomes its convex hull, simplified to at most 64 corners as the game's own props are. A concave model such as a chair tumbles as its outline. Flat meshes such as decals and loose paper are refused, because a body needs volume. The preview shows the hull, marked not yet a system, while a dialog asks for the new system's settings:

The Physics System Editor previewing a 46-corner hull of SHIP_SMALL_BRIDGE_PILOTCHAIR_DISPLAY as a flat, rounded slab in blue, with the body list empty, Edit Body... greyed out, and the status line reading 46-corner hull of SHIP_SMALL_BRIDGE_PILOTCHAIR_DISPLAY ยท not yet a system.

The New Physics System dialog: 46-corner convex hull of SHIP_SMALL_BRIDGE_PILOTCHAIR_DISPLAY (simplified from 81), volume 67.039 L, convex radius 1.09 cm, one dynamic body; then System name OPENCAGE\IMPORTED, Body name Body, Mass (kg) 20.10, Friction 0.50, Restitution 0.40, and a greyed Placement box reading No model in the composite to place it at, with Create System and Cancel buttons.

A pilot chair imported with From Model...: its legs and seat become one 46-corner hull, simplified from 81.

  • System name and Body name: opened from Set Physics..., these follow the retail convention: the system is named after the composite and the body after the composite's ModelReference. Opened from View, they're placeholders.
  • Mass (kg): suggested from the hull's volume, between 0.1 and 50 kg. Friction and restitution start at 0.5 and 0.4. All three can be changed later with Edit Body....
  • Placement: opened from Set Physics..., this puts the body where the composite's model sits, as the game's own props are, so the body lines up with what's drawn. Opened from View there's no composite, so it's greyed out.

Create System adds it at the end of the list with the next index, selected. Cancel puts the preview back.

Assigning a System

Opened from Set Physics..., the window starts with the entity's current system selected. Select another (a new import is already selected) and click Select System, or double-click its row, to give it to the entity and close the window. Opened from View, Select System is hidden and a double-click only selects the row.

Save and Build then puts the system in the world wherever the PhysicsSystem entity is.

Saving

The editor has no Save button of its own. Imported systems and edited bodies are held in memory and written when you save the level with File โ†’ Save Level (Ctrl+S). On PC that's both PHYSICS.HKX and PHYSICS.HKX64, which always get the same change. A mobile or Switch level has only the 64-bit file, so an import writes only that one.