CharacterBody
A body that walks, jumps, falls and collides with the world. It climbs shallow steps, sticks to slopes going downhill, and reports whether it is standing on the floor, a wall or a ceiling.
On this page
Add it
+ Add node → Character, Root Motion Character creates a node with it already on. Already have a node for it? Add component → CharacterBodyComponent.
From a script
A script on the same node writes these fields by name. CharacterBodyComponent is the name to pass.
rgs
set_point("CharacterBodyComponent", "size", vec2(32.0, 48.0));
set_point("CharacterBodyComponent", "velocity", vec2(0.0, 0.0));
set_number("CharacterBodyComponent", "gravity", 1800.0);
set_number("CharacterBodyComponent", "terminal_velocity", 900.0);
set_number("CharacterBodyComponent", "speed", 220.0);
set_number("CharacterBodyComponent", "jump_speed", 620.0);
set_number("CharacterBodyComponent", "coyote_time", 0.0);
set_number("CharacterBodyComponent", "jump_buffer", 0.0);
set_number("CharacterBodyComponent", "jump_cut", 1.0);
set_number("CharacterBodyComponent", "swim_stroke", 0.0);
set_number("CharacterBodyComponent", "rope_jump", 0.0);
set_number("CharacterBodyComponent", "step_height", 0.0);
set_number("CharacterBodyComponent", "floor_snap_length", 0.0);
set_number("CharacterBodyComponent", "floor_max_angle", 0.7853982);
set_flag("CharacterBodyComponent", "pushable", false);
set_number("CharacterBodyComponent", "push_speed", 0.5);
set_flag("CharacterBodyComponent", "grounded", false);
set_flag("CharacterBodyComponent", "on_wall", false);
set_flag("CharacterBodyComponent", "shoving", false);
set_flag("CharacterBodyComponent", "on_ceiling", false);
set_flag("CharacterBodyComponent", "drop_through", false);
set_colour("CharacterBodyComponent", "debug_color", vec4(0.35, 0.85, 0.55, 0.35));Fields
| Field | Script name | Kind | Default | What it does |
|---|---|---|---|---|
| Size | size | two numbers (x, y) | (32, 48) | Collision box size in world units, anchored at the feet. |
| Motion Mode | motion_mode | one of Grounded, Floating | Grounded | Grounded: gravity pulls it down. Floating: no gravity, and every surface blocks it like a wall. |
| Driven By | driven_by | one of Keys, Script | Keys | Keys: the project's left and right actions walk it (A and D or the arrows, unless the Input window binds them otherwise; its move action, where it has a move and no left or right), turning it to face the way it walks, and its jump action (Space) jumps it when it is Grounded; up and down walk it the other two ways when it is Floating (move again, where it has neither). Script: its script sets its speed and calls jump(). |
| Velocity | velocity | two numbers (x, y) | (0, 0) | Current velocity, in units per second. |
| Drift | drift | two numbers (x, y), read-only | (0, 0) | What the world adds to this body's own velocity: wind, a magnet, a belt, a current, a shove, a swing. Read only. |
| Gravity | gravity | number, at least 0 | 1800 | Positive; down counts as positive here. |
| Terminal Velocity | terminal_velocity | number, at least 1 | 900 | Fastest the body may fall. |
| Speed | speed | number, at least 0 | 220 | How fast the keys walk it; a script that drives it sets its own speed. |
| Jump Speed | jump_speed | number, at least 0 | 620 | Upward speed applied by a jump. |
| Jumping | ||||
| Coyote Time | coyote_time | number, at least 0, step 0.01 | 0 | Seconds after running off a ledge in which a jump still counts. |
| Jump Buffer | jump_buffer | number, at least 0, step 0.01 | 0 | Seconds a jump asked for just before landing waits to happen on landing. |
| Jump Cut | jump_cut | number, 0 to 1, step 0.05 | 1 | How much of the rise is kept when the jump is let go early; 1 keeps all of it. |
| Air Jumps | air_jumps | number, 0 to 8 | 0 | How many more jumps it may make in the air before it lands again. |
| Swim Stroke | swim_stroke | number, at least 0, step 10 | 0 | Upward speed a Jump press sets while the body's middle is under a Buoyancy waterline and it is neither grounded nor within its Coyote Time; 0 cannot swim. |
| Rope Jump | rope_jump | number, at least 0, step 10 | 0 | Upward speed a Jump press sets while the body hangs on a rope — held by an enabled joint, neither grounded nor within its Coyote Time; 0 cannot. It does not let go of the rope: the script that holds the joint does. |
| Slopes | ||||
| Step Height | step_height | number, at least 0, step 1 | 0 | Steps up to this height are climbed automatically, from the ground or by a body landing on it this step; a body in the air otherwise, or afloat, climbs onto nothing. Zero climbs none of them. |
| Floor Snap Length | floor_snap_length | number, at least 0, step 1 | 0 | Keeps this body's feet on the ground going downhill; zero lets it launch off every step. |
| Floor Max Angle | floor_max_angle | number, at least 0, step 0.01 | 0.7854 | In radians; anything steeper than this counts as a wall, not a floor. |
| Max Slides | max_slides | number, 1 to 8 | 1 | How many times a blocked move is retried each step, so it can slide around corners. |
| Pushing | ||||
| Pushable | pushable | checkbox | off | A body that walks into this one shoves it along instead of stopping. It needs a solid Collider of its own to be walked into. |
| Push Speed | push_speed | number, 0 to 1, step 0.05 | 0.5 | How much of the pusher's speed a shove gives this body: 1 keeps pace with the pusher, 0.5 moves at half its speed. |
| Grounded | grounded | checkbox | off | Whether something solid is directly below. |
| On Wall | on_wall | checkbox | off | Horizontal motion was blocked on the last step. |
| Shoving | shoving | checkbox | off | Shoving a pushable body along on the last step. One that will not give way counts as a wall instead. |
| On Ceiling | on_ceiling | checkbox | off | Upward motion was blocked on the last step. |
| Drop Through | drop_through | checkbox | off | Ignoring one-way platforms while leaving one: set and cleared in the step the body leaves the plank. |
| Layer | layer | number | 1 | Which physics layers this body is on. |
| Debug Color | debug_color | colour | #59d98c, 35% opaque | Tint for the editor's debug box. |