Movement & Character Controller

public interface IKinematicCharacterController3D
{
    void SetBody(IPhysxBody3D body);
    void SetMovementInput(ICharacterMovementInput3D input);
    void AddLocalMotionDelta(Vector3 localDelta);
    void Step(float dt, IGameWorldManager3D world);

    Vector3 Position { get; }
    Quaternion Rotation { get; }
    float Yaw { get; }
    bool IsGrounded { get; }
    Vector3 Velocity { get; }
    CharacterMovementFrame3D LastMovementFrame { get; }
    bool HasActiveMovementInput { get; }
}

public async Task SetupCharacter(CharacterPrefab prefab, IGameWorldManager3D world)
{
    // 1. Create body profile (capsule shape for humanoid)
    var profile = new HumanoidCapsuleBodyProfile(
        radius: 0.28f,
        halfLength: 0.62f,
        mass: 0f,
        isKinematic: true
    );

    // 2. Set physics descriptors on the prefab
    prefab.BodyDescriptor = profile.CreateBody(prefab.Transform);
    prefab.ColliderDescriptors = profile.CreateColliders(prefab.Transform);

    // 3. Spawn into world (creates the runtime physics body)
    var body = await world.SpawnDynamicObject(prefab);

    // 4. Create and configure the controller
    var controller = new KinematicCharacterController3D
    {
        Radius = 0.28f,
        Height = 1.8f,
        PivotToCenterY = 0.9f,
        MaxSlopeAngleDeg = 60f,
        MovementProfile = TpsMovementProfile3D.Default,
        MovementStats = new CharacterMovementStats3D(
            WalkSpeed: 5f,
            SprintSpeed: 8f,
            MoveSpeedMultiplier: 1f,
            RotationSpeedDegPerSec: 720f),
    };

    // 5. Add abilities
    controller.AddAbility(new SimpleJumpAbility3D { JumpSpeed = 7.5f });

    // 6. Attach the runtime physics body
    controller.SetBody(body);
}

public readonly record struct CharacterRealtimeWasdInput3D(
    float MoveX,
    float MoveZ,
    Vector3 LookDirection,
    float CameraYaw,
    float ExternalFacingYaw,
    bool UseExternalFacing,
    bool Sprint,
    bool Jump) : ICharacterMovementInput3D;

public readonly record struct CharacterClickToMoveInput3D(
    Vector3 TargetWorldPosition,
    float ArrivalDistance,
    bool Sprint = false) : ICharacterMovementInput3D;

public readonly record struct CharacterMovementStats3D(
    float WalkSpeed,
    float SprintSpeed,
    float MoveSpeedMultiplier,
    float RotationSpeedDegPerSec);

controller.MovementProfile = TpsMovementProfile3D.Default;
controller.MovementStats = new CharacterMovementStats3D(
    WalkSpeed: 5f,
    SprintSpeed: 8f,
    MoveSpeedMultiplier: 1f,
    RotationSpeedDegPerSec: 720f);

controller.SetMovementInput(new CharacterClickToMoveInput3D(
    TargetWorldPosition: clickPoint,
    ArrivalDistance: 0.15f,
    Sprint: false));

[Gate("move")]
public void OnMove(MovePacket packet, string clientId)
{
    var prefab = GetPlayerPrefab(clientId);

    prefab.Controller.SetMovementInput(new CharacterRealtimeWasdInput3D(
        MoveX: packet.InputX,
        MoveZ: packet.InputZ,
        LookDirection: new Vector3(packet.LookX, packet.LookY, packet.LookZ),
        CameraYaw: packet.CameraYaw,
        ExternalFacingYaw: packet.ExternalFacingYaw,
        UseExternalFacing: packet.UseExternalFacing,
        Sprint: packet.Sprint,
        Jump: packet.Jump));
}

[Prefab("character")]
[WorldObject("character")]
public class CharacterPrefab : WorldObjectPrefab3D
{
    [PrefabComponentRoot]
    public CharacterVault Character { get; set; } = default!;

    public IKinematicCharacterController3D Controller { get; set; } = default!;

    public override void Step(float dt, IGameWorldManager3D world)
    {
        if (Controller is null) return;

        Controller.Step(dt, world);

        Transform = Transform
            .WithPosition(Position3D.From(Controller.Position))
            .WithRotation(Rotation3D.FromQuaternion(Controller.Rotation));

        Character.X = Transform.Position.X;
        Character.Y = Transform.Position.Y;
        Character.Z = Transform.Position.Z;
    }
}

public struct CharacterMotorContext
{
    public IPhysxBody3D Body;
    public IGameWorldManager3D World;

    public Vector3 DesiredMoveWorld;
    public float DesiredSpeed;
    public Vector3 Velocity;

    public bool IsGrounded;
    public Vector3 GroundNormal;

    public bool JumpPressed;
    public bool SprintHeld;
}

controller.AddAbility(new SimpleJumpAbility3D { JumpSpeed = 7.5f });

public class DashAbility : ICharacterAbility3D
{
    public float DashSpeed { get; set; } = 20f;
    public float DashDuration { get; set; } = 0.2f;

    private float _dashTimer;
    private bool _wasDashPressed;

    public void Step(float dt, ref CharacterMotorContext ctx)
    {
        bool dashPressed = ctx.SprintHeld;
        bool pressedThisFrame = dashPressed && !_wasDashPressed;
        _wasDashPressed = dashPressed;

        if (_dashTimer > 0f)
        {
            _dashTimer -= dt;
            if (ctx.DesiredMoveWorld.LengthSquared() > 0.01f)
            {
                var dashDir = Vector3.Normalize(ctx.DesiredMoveWorld);
                ctx.Velocity = new Vector3(
                    dashDir.X * DashSpeed,
                    ctx.Velocity.Y,
                    dashDir.Z * DashSpeed);
            }
            return;
        }

        if (pressedThisFrame && ctx.IsGrounded)
            _dashTimer = DashDuration;
    }
}

controller.AddAbility(new DashAbility { DashSpeed = 25f, DashDuration = 0.15f });

public class DoubleJumpAbility : ICharacterAbility3D
{
    public float JumpSpeed { get; set; } = 6f;
    public int MaxAirJumps { get; set; } = 1;

    private int _airJumpsUsed;
    private bool _wasPressed;
    private bool _wasGrounded;

    public void Step(float dt, ref CharacterMotorContext ctx)
    {
        if (ctx.IsGrounded && !_wasGrounded)
            _airJumpsUsed = 0;

        _wasGrounded = ctx.IsGrounded;

        bool pressedThisFrame = ctx.JumpPressed && !_wasPressed;
        _wasPressed = ctx.JumpPressed;

        if (!pressedThisFrame) return;

        if (!ctx.IsGrounded && _airJumpsUsed < MaxAirJumps)
        {
            ctx.Velocity = new Vector3(ctx.Velocity.X, JumpSpeed, ctx.Velocity.Z);
            ctx.IsGrounded = false;
            _airJumpsUsed++;
        }
    }
}

controller.AddAbility(new SimpleJumpAbility3D { JumpSpeed = 7.5f });
controller.AddAbility(new DoubleJumpAbility { JumpSpeed = 6f, MaxAirJumps = 1 });

Vector3 pos = controller.Position;
Quaternion rot = controller.Rotation;
float yaw = controller.Yaw;
bool grounded = controller.IsGrounded;
Vector3 vel = controller.Velocity;
CharacterMovementFrame3D frame = controller.LastMovementFrame;

var syncPacket = new PositionSyncPacket
{
    EntityId = prefab.EntityId,
    X = controller.Position.X,
    Y = controller.Position.Y,
    Z = controller.Position.Z,
    Yaw = controller.Yaw,
    Speed = controller.Velocity.Length(),
    Grounded = controller.IsGrounded,
};

var profile = new HumanoidCapsuleBodyProfile(
    radius: 0.28f,
    halfLength: 0.62f,
    mass: 0f,
    isKinematic: true
);

prefab.BodyDescriptor = profile.CreateBody(prefab.Transform);
prefab.ColliderDescriptors = profile.CreateColliders(prefab.Transform);

public class VehicleBodyProfile : IBodyProfile3D
{
    public float Width { get; }
    public float Height { get; }
    public float Length { get; }
    public float Mass { get; }

    public VehicleBodyProfile(float width, float height, float length, float mass)
    {
        Width = width;
        Height = height;
        Length = length;
        Mass = mass;
    }

    public PhysxBody3DDesc CreateBody(Transform3D transform)
    {
        var sized = transform.WithSize(Size3D.Of(Width / 2, Height / 2, Length / 2));
        return PhysxBody3D.Create(PhysxBodyType.Dynamic, Mass, sized);
    }

    public IEnumerable<PhysxCollider3DDesc> CreateColliders(Transform3D transform)
    {
        var sized = transform.WithSize(Size3D.Of(Width / 2, Height / 2, Length / 2));
        yield return PhysxCollider3D.Create(PhysxColliderShape3D.Box3D, sized, isTrigger: false);
    }
}