Physics
physicsCreate and configure Godot bodies, collision shapes, layers, joints, raycasts, and project settings like gravity or tick rate.
Instructions
Physics bodies and collision: create a body/area with its collision shape (and optionally its sprite/mesh, auto-fitted) in one call, fit shapes to visuals, set collision layers/masks by name, add joints, raycast the edited scene, and change project physics settings (gravity, tick rate, engine).
Actions:
body: {type: static_2d|character_2d|rigid_2d|area_2d|animatable_2d|static_3d|character_3d|rigid_3d|area_3d|animatable_3d (or a class name), name?, parent?='.', position?, rotation? (degrees), shape?: {type: rect|circle|capsule|segment|world_boundary|convex|concave|polygon (2D) | box|sphere|capsule|cylinder|world_boundary|convex|concave|polygon (3D), size?, radius?, height?, points?, position?, rotation?, one_way?, disabled?} (default rect 32x32 / box 1m), shapes?: [several], sprite?: res://img.png (adds Sprite2D/Sprite3D) | mesh?: {type: 'BoxMesh', size: [1,1,1]} (adds MeshInstance3D) — the first shape is fitted to the visual (its opaque pixels) when it has no size/radius/points, layer?: [names|numbers], mask?: [names|numbers], script?, groups?, props?, visual_props?, children?: [node specs]} create a physics body + CollisionShape (+ visual) in one undoable step.
fit_shape: {path: body, its CollisionShape, or its Sprite2D/MeshInstance3D child, from?: visual node path (default: first Sprite2D/AnimatedSprite2D/MeshInstance3D/Sprite3D child), kind?: rect|circle|capsule|convex (2D, convex traces sprite alpha) | box|sphere|capsule|cylinder|convex|trimesh (3D), grow?: px/units (negative shrinks), trim?=true (2D: fit the opaque pixels of the current frame, not the padded frame rect)} size the collision shape to the visual (sprite frame incl. hframes/vframes/region/scale/flip; mesh AABB or hull). Creates the CollisionShape if missing.
layers: {path | paths, layer?: ['player'] | [2], mask?: ['world', 'enemies'] | [1, 3], mode?: set|add|remove} set collision_layer/mask using layer names from project settings (name them with project.set_layer_name) or layer numbers 1-32 (not bitmasks). Without layer/mask: shows current layers by name.
joint: {type: pin_2d|groove_2d|damped_spring_2d|pin_3d|hinge_3d|slider_3d|cone_3d|generic_6dof_3d, node_a, node_b, parent?=node_a's parent, name?, position? (parent space) | at?: mid|a|b (default mid), props?} connect two physics bodies. Groove/spring length defaults to the distance between the bodies.
raycast: {from: [x,y] | [x,y,z], to, mask?: names|numbers, areas?: bool, type?: 2d|3d} cast a ray in the edited scene (editor world, global coordinates): hit collider, position, normal. For the running game use game.raycast.
settings: {gravity?, gravity_direction?, linear_damp?, angular_damp?, engine_3d?: DEFAULT|GodotPhysics3D|Jolt Physics, gravity_2d?, gravity_direction_2d?, linear_damp_2d?, angular_damp_2d?, engine_2d?, ticks_per_second?, max_steps_per_frame?, jitter_fix?, interpolation?, settings?: {'physics/...': value}} read/change project physics settings (no args = read). 2D gravity is px/s² (default 980), 3D m/s² (9.8).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Joint anchor: mid | a | b. | |
| to | No | ||
| from | No | ||
| grow | No | fit_shape: grow (or shrink if negative) the fitted shape. | |
| kind | No | fit_shape: shape kind. | |
| mask | No | ||
| mesh | No | ||
| mode | No | layers: set | add | remove. | |
| name | No | Node name. | |
| path | No | Node path relative to the scene root ('.' = root, 'Player/Sprite2D', '%Unique'), or a res:// file path, depending on the action. | |
| trim | No | fit_shape: fit opaque sprite pixels (default true) instead of the whole frame. | |
| type | No | Body type (body) or joint type (joint). | |
| areas | No | raycast: also hit Areas. | |
| layer | No | ||
| paths | No | Several node paths (layers). | |
| props | No | Property map. Values are coerced to the property type: numbers, [x,y], 'Vector2(1,2)', '#ff8800', 'res://file', {"type":"RectangleShape2D","size":[32,32]} for new resources, enum names as strings. | |
| scene | No | res:// scene to operate on; opened in the editor if needed. Defaults to the currently edited scene. | |
| shape | No | ||
| action | Yes | What to do. See the tool description for each action's parameters. | |
| groups | No | Groups to add the body to. | |
| node_a | No | First body of the joint. | |
| node_b | No | Second body of the joint. | |
| parent | No | Parent node path. | |
| script | No | res:// script to attach to the body. | |
| shapes | No | Several shape specs. | |
| sprite | No | res:// texture: adds a Sprite2D (2D) / Sprite3D (3D) child. | |
| gravity | No | 3D gravity m/s². | |
| children | No | Extra child node specs {type, name?, props?}. | |
| position | No | [x, y] or [x, y, z]. | |
| rotation | No | ||
| settings | No | Raw physics settings {'physics/2d/default_gravity': 980}. | |
| engine_2d | No | 2D physics engine. | |
| engine_3d | No | 3D physics engine. | |
| gravity_2d | No | 2D gravity px/s². | |
| jitter_fix | No | Physics jitter fix. | |
| linear_damp | No | 3D default linear damp. | |
| angular_damp | No | 3D default angular damp. | |
| visual_props | No | Properties for the created sprite/mesh node. | |
| interpolation | No | Physics interpolation. | |
| linear_damp_2d | No | 2D default linear damp. | |
| angular_damp_2d | No | 2D default angular damp. | |
| ticks_per_second | No | Physics ticks per second (default 60). | |
| gravity_direction | No | 3D gravity vector. | |
| max_steps_per_frame | No | Max physics steps per frame. | |
| gravity_direction_2d | No | 2D gravity vector. |