Struct CharacterBody

struct CharacterBody

Public Functions

CharacterBody(Object *owner_)
void configure(const Settings &s)

Applies settings in bulk (e.g.

from editor init data). Refreshes all internal caches derived from settings.

inline const Settings &getSettings() const

Read-only access to current settings.

inline const fm_vec3_t &getVelocity() const

Returns the current internal velocity (after gravity + slide projection).

Returns:

velocity

inline void setVelocity(const fm_vec3_t &newVelocity)

Override the full internal velocity (e.g.

to perform a jump impulse on Y). For normal movement prefer setting ‘inputVelocity’.

Parameters:

newVelocity –

inline bool isOnFloor() const

Check the current grounded state.

Returns:

true if standing on a floor or steep surface

inline const fm_vec3_t &floorNormal() const

Returns the normal of the last floor, including steep surfaces.

Returns:

normal

fm_vec3_t getFootPos() const

World-space position of the bottom of the capsule.

Returns:

foot position in world space

inline uint16_t floorObjectId() const

Object id of the surface the body is currently grounded on (0 when airborne).

Lets other objects react to the character standing on them (e.g. platforms, pressure plates) now that the body produces no collision events itself.

Returns:

id of the floor object, or 0

inline bool wasMovedByFloor() const

Whether the floor moved (carried) the body this frame via followFloor — i.e.

the surface it stands on translated or rotated and dragged the body along. Useful e.g. to avoid banking a respawn point while on a moving platform. Note: only reflects followFloor carry (mesh-collider floors).

Returns:

true if a moving floor carried the body this frame

inline bool isOnSteepSurface() const

True when the body is on an upward-facing surface steeper than the limit.

If this is the case, isOnFloor() will also return true. This function here can be used to determine on which of the two you are standing

Returns:

void setUp(const fm_vec3_t &newUp)

Sets the body’s up vector and refreshes internal caches.

The input does not need to be pre-normalized.

Parameters:

newUp – new up direction

void setCenterOffset(const fm_vec3_t &offset)

Sets the center offset and refreshes the cached rotated offset.

Parameters:

offset – offset in meters from the object origin to the capsule center

void teleport(const fm_vec3_t &ownerPos, bool resetForces = true)

Instantly moves the character to a new owner position.

When resetForces is true (default), also zeroes velocity and clears the grounded state so the body starts clean, use this for respawning. When false, only the position changes (e.g. portal / seamless teleport).

Parameters:

  • ownerPos – New position in world space (same space as Object::pos).

  • resetForces – If true, zero velocity and clear grounded state.

void moveAndSlide(float deltaTime)

Performs movement for the body.

Handles: gravity, sweeps, slides on hits, snaps to floor, then writes the final position back to the owning Object.

Parameters:

deltaTime – time step to move for, in seconds

void debugDraw() const

Draws the capsule shape and floor-snap probe in debug wireframe.

Call once per frame after moveAndSlide.

Public Members

fm_vec3_t inputVelocity = {}

velocity to be applied during the next ‘moveAndSlide’ call.

struct Settings

Public Members

fm_vec3_t up = {0.0f, 1.0f, 0.0f}
fm_vec3_t centerOffset = {0.0f, 0.0f, 0.0f}
float gravity = {30.0f}

Offset in meters from the object origin to the capsule center.

float maxFallSpeed = {55.0f}
float floorMaxAngle = {45.0_deg}
float stepHeight = {0.25f}

Max height of a step the character automatically climbs.

The physics capsule is shortened from the bottom by this amount, making stair risers below this height invisible to collision. The floor snap then lifts the character up. Must be <= innerHalfHeight (height/2 - radius). floorSnapDistance must be >= stepHeight for stair climbing to work.

float floorSnapDistance = {0.30f}

How far below the full capsule bottom the floor snap probe reaches.

Controls sticking to ground on slopes and snapping over step edges. Must be >= stepHeight for stair climbing to work.

float radius = {0.5f}
float height = {2.0f}

Capsule total height in meters (including both hemispherical caps).

Must be >= 2 * radius, values below that clamp to a sphere.

RaycastColliderTypeFlags collTypes = {RaycastColliderTypeFlags::MESH_COLLIDERS}
uint8_t maxSlides = {4}
uint8_t readMask = {0xFF}
bool followFloor = {true}

When true, position is carried along with the mesh collider currently stood on (translation + rotation of the contact point).

The character’s own facing is not changed.