> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/what-physics-and-rapier-mean.md). # What physics and Rapier mean in Sandbox Studio When Play mode runs, something has to decide which objects are solid, which fall, and how the player slides along floors. That work is **physics**. Sandbox Studio runs it with a library called **Rapier**. You do not install Rapier, open its docs, or call it by name for normal level work. You turn physics on or off on nodes and set a few Inspector fields. If the console or the agent mentions Rapier, treat it as a clue that a collider or motion setting on a node is wrong — not as a signal to learn a second engine. ## What you set in Studio Physics lives on placeable geometry nodes (Mesh Nodes, Model Mesh Nodes, and other `PrimitiveNode` types). The look of a mesh and whether it blocks the player are separate. A pretty `.glb` can have physics off. A hidden capsule can be the only thing the player bumps. | Field | What it controls | | ----------------- | ------------------------------------------------- | | Physics enabled | Whether this node has a body in the physics world | | Motion | How that body is allowed to move | | Collision mesh | The shape used for hits (for model meshes) | | Collision profile | Who this body blocks or overlaps | Step-by-step on kit pieces and navmesh: [How to set collision and navmesh on mesh models](/the-editor/how-to-set-collision-and-navmesh-on-mesh-models.md). ## Motion | Motion | Use when | | ------------------------ | -------------------------------------------------------------------------------- | | `static` | Floors, walls, kit modules that never move. Default after you drag a `.glb` | | `dynamic` | Objects that should fall, tumble, or be shoved by forces | | `kinematicPositionBased` | Bodies the game moves by setting position (the Character Pawn capsule uses this) | | `kinematicVelocityBased` | Bodies the game moves by setting velocity | Do not make the player’s **visible** mesh `dynamic` and expect a clean walk controller. The pawn already owns a capsule for that job. ## Collision mesh These shapes matter for Model Mesh Nodes and similar non-primitive meshes: | Type | Tradeoff | | ---------------- | --------------------------------------------------------------------------- | | `boundingBox` | Cheap box around the mesh. Good when a tight hull is wrong or too expensive | | `boundingSphere` | Cheap sphere. Rare for rooms; useful for rough blobs | | `convexHull` | Default after a drag. Fits chunky props and simple ground better than a box | | `trimesh` | Follows the triangles. Heaviest. Engine notes it for **static** objects | Hundreds of `convexHull` colliders on decorative kit pieces will cost CPU. Turn physics **off** on dressing. See [Performance & optimization](/the-editor/performance-and-optimization.md). ## Profiles you will actually use A **profile** decides who this collider interacts with. You do not need the full list to ship a room. | Profile | Typical use | | ---------------------------------- | ------------------------------------------------------------------------------- | | `BlockAll` | Solid scenery. Default for a dragged kit piece | | `Character` | The pawn capsule. Ships on Character Pawn | | `Trigger` / overlap-style profiles | Volumes that detect the player without stopping them (doors, pickups, switches) | Triggers and interactables: [Doors, switches, pickups and triggers](/the-editor/doors-switches-pickups-and-triggers.md). ## Player vs scenery The Character Pawn keeps collision on a **capsule** (profile `Character`, motion `kinematicPositionBased`) and leaves physics **off** on the visual `.glb`. If you turn physics on the visible mesh, the body becomes a second wall. Full tree: [How to use a character pawn](/the-editor/how-to-use-a-character-pawn.md). Kit modules that should stop the pawn: physics on, motion `static`, profile `BlockAll`, then pick a collision mesh that matches the shape. Cards, banners, and sky dressing: physics off. ## Physics is not navmesh Physics is what the **pawn** bumps into. **Navmesh** is the walkable map AI uses (`navigationGeometryRole`: `walkable`, `obstacle`, `exclude`). A mesh can block the player and still be excluded from the bake. Set both on purpose. Details: [How to set collision and navmesh on mesh models](/the-editor/how-to-set-collision-and-navmesh-on-mesh-models.md). ## Practical guidance * Fix solid floors and walls with Inspector physics on the nodes you stand on — not by searching for Rapier tutorials. * After a drag, leave solid modules at `static` + `BlockAll` + `convexHull` until Play proves the shape is wrong; then try `boundingBox` or a simpler Mesh Node collider. * Keep physics off on the character visual and on decorative props. * When FPS drops in a busy room, audit physics-enabled meshes before blaming texture size. * Prefer prefabs for reusable setups. Do not flatten every room into unique in-scene meshes only to “avoid physics bugs” unless engineering confirms a known limitation. ## Common mistakes | What went wrong | What to do | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Heard “Rapier” and opened external physics docs | Adjust the node’s physics fields in Studio. Link this page for the agent. | | Visual character mesh has physics on | Turn it off. Collision is the capsule. | | Every kit prop is a `convexHull` wall | Physics off on dressing. Measure FPS. | | Pawn falls through the floor | Floor needs physics on, `static`, `BlockAll`, and Player Start on that surface. | | AI walks through a wall that blocks the player | Set `navigationGeometryRole` and regenerate navmesh. That is not a Rapier profile. | | Avoided prefabs after a physics update broke a room | File an engine issue with repro. Keep using prefabs for reuse until a supported workaround is documented. | ## What You've Done You know Rapier is the physics library under Studio, and that creators control it through node fields: enabled, motion, collision mesh, and profile. Next: set a room on [How to set collision and navmesh on mesh models](/the-editor/how-to-set-collision-and-navmesh-on-mesh-models.md), check the pawn tree on [How to use a character pawn](/the-editor/how-to-use-a-character-pawn.md), or read [What JSON files are in Sandbox Studio](/the-editor/what-json-files-are.md) and [What Three.js means in Sandbox Studio](/the-editor/what-threejs-means.md) if those names show up in errors or agent chat. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://studio-docs.sandbox.game/the-editor/what-physics-and-rapier-mean.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.