character3d component

A 3D character controller: physics3d.move_character slides the node along walls and steps it up ledges. Needs a collider3d; a kinematic body3d lets it…

På denne side

Properties
Script functions

3d · physics · 18 properties · 3D

A 3D character controller: physics3d.move_character slides the node along walls and steps it up ledges. Needs a collider3d; a kinematic body3d lets it push bodies.

In a scene, character3d is the node key that applies it. A script reaches each property below as a field on node.character3d: reading one asks the running component, and assigning one leaves the rest alone. The whole table is node.character3d.get() and node.character3d.set(table).

Properties

property	type	default	description
`floor_max_angle`	float	`0.7853982`	The steepest slope the character may walk up; radians in the file, degrees in the inspector Range 0–90.
`floor_snap_length`	float	`0.2`	How far below its feet the character looks for ground to stay stuck to over a crest; 0 turns snapping off At least 0.
`floor_snap_lengths`	enum	`absolute`	Whether floor_snap_length is in world units or a fraction of the character's shape: relative is measured against the height along up_direction One of `absolute`, `relative`.
`ignore`	flags	`["sensors"]`	What a move passes through: static takes colliders with no body too. The character's own collision_layer and collision_mask filter the rest One of `static`, `kinematic`, `dynamic`, `sensors`, `solids`.
`ignore_nodes`	list	`[]`	Nodes a move passes through: their colliders, and every collider on their body
`min_slide_angle`	float	`0.5235988`	The shallowest slope the character slides back down; radians in the file, degrees in the inspector Range 0–90.
`normal_nudge`	float	`0.0001`	A tiny push along the contact normal that stops the character catching on seams At least 0.
`push_bodies`	bool	`true`	Push dynamic bodies the character walks into, rather than passing through them
`push_mass`	float	`0`	The mass a push is worked out with; 0 takes the body's mass, or the colliders' when there is no body At least 0.
`safe_margin`	float	`0.01`	A gap kept between the character and everything else, so the solver never has to push it out of a wall At least 0.
`safe_margin_lengths`	enum	`absolute`	Whether safe_margin is in world units or a fraction of the character's shape: relative is measured against the height along up_direction One of `absolute`, `relative`.
`slide`	bool	`true`	Slide along what is in the way instead of stopping dead against it
`step_height`	float	`0.3`	The tallest step the character climbs without jumping; 0 turns stepping off At least 0.
`step_height_lengths`	enum	`absolute`	Whether step_height is in world units or a fraction of the character's shape: relative is measured against the height along up_direction One of `absolute`, `relative`.
`step_min_width`	float	`0.2`	How much clear ground a step needs on top before it may be climbed At least 0.
`step_min_width_lengths`	enum	`absolute`	Whether step_min_width is in world units or a fraction of the character's shape: relative is measured against the width across up_direction One of `absolute`, `relative`.
`step_on_dynamic`	bool	`false`	Climb onto dynamic bodies too, not only static and kinematic ones
`up_direction`	vec3	`[0,1,0]`	Which way is up for this character: the axis it stands along and measures slopes against

Script functions

Methods of node.character3d, the handle a node carrying this component exposes. Every handle also has get(), set(table), patch(table), has() and remove().

From physics3d:

method what it does

is_on_floor() -> bool Whether the last move ended with ground under the character's feet.

move_character(float, float, float) -> any Move the character by an offset, sliding along walls, climbing steps and staying on the ground: returns #{ x, y, z, on_floor, sliding, collisions }, each collision #{ node, point, normal, own_point, own_normal, position, applied, remaining, distance, status, subshape }: the hit on the obstacle and on the character in world space, where the character stood, how much of the move was done and left, how far it swept, how the sweep ended (converged, out_of_iterations, failed, penetrating) and which part of the obstacle's shape it met. Every solid collider of the character is swept. Call it from fixed_update. It reads the world the step just wrote.

method	what it does
`is_on_floor() -> bool`	Whether the last move ended with ground under the character's feet.
`move_character(float, float, float) -> any`	Move the character by an offset, sliding along walls, climbing steps and staying on the ground: returns `#{ x, y, z, on_floor, sliding, collisions }`, each collision `#{ node, point, normal, own_point, own_normal, position, applied, remaining, distance, status, subshape }`: the hit on the obstacle and on the character in world space, where the character stood, how much of the move was done and left, how far it swept, how the sweep ended (`converged`, `out_of_iterations`, `failed`, `penetrating`) and which part of the obstacle's shape it met. Every solid collider of the character is swept. Call it from fixed_update. It reads the world the step just wrote.