Movement & Character Controller

public interface IKinematicCharacterController3D
{
    // Attach the physics body
    void SetBody(IPhysxBody3D body);

    // Input intents (called by netcode)
    void MoveIntent(float moveX, float moveZ);
    void LookIntent(float lookX, float lookY, float lookZ);
    void SprintIntent(bool sprintHeld);
    void JumpIntent(bool jumpPressed);

    // Simulation tick (called by prefab/world Step)
    void Step(float dt, IGameWorldManager3D world);

    // State outputs (for replication)
    Vector3 Position { get; }
    Quaternion Rotation { get; }
    bool IsGrounded { get; }
    Vector3 Velocity { 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,     // (height/2) - radius
        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
    {
        MoveSpeed = 5f,
        SprintSpeed = 8f,
        Gravity = 25f,
        MaxSlopeAngleDeg = 60f,
        Radius = 0.28f,
        Height = 1.8f,
    };

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

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

[Gate("move")]
public void OnMove(MovePacket packet, string clientId)
{
    var prefab = GetPlayerPrefab(clientId);
    prefab.Controller.MoveIntent(packet.InputX, packet.InputZ);
    prefab.Controller.LookIntent(packet.LookX, packet.LookY, packet.LookZ);
    prefab.Controller.SprintIntent(packet.Sprint);
    prefab.Controller.JumpIntent(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 (Body is not IPhysxBody3D body || Controller is null) return;

        // 1. Run the controller physics
        Controller.Step(dt, world);

        // 2. Sync transform from physics body
        Transform = Transform
            .WithPosition(Position3D.From(body.Position))
            .WithRotation(Rotation3D.FromQuaternion(body.Rotation));

        // 3. Persist to vault for database save
        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;  // Normalized input direction in world space
    public float DesiredSpeed;        // Target speed (m/s)
    public Vector3 Velocity;          // Current velocity (mutable — abilities modify this)

    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)
    {
        // Reset air jumps when landing
        if (ctx.IsGrounded && !_wasGrounded)
            _airJumpsUsed = 0;

        _wasGrounded = ctx.IsGrounded;

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

        if (!pressedThisFrame) return;

        // Airborne jump
        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;         // Current body position
Quaternion rot = controller.Rotation;      // Current body rotation
bool grounded = controller.IsGrounded;     // Whether on ground
Vector3 vel = controller.Velocity;         // Current velocity

// In your broadcast service / visibility handler
var syncPacket = new PositionSyncPacket
{
    VirtualId = prefab.VirtualId,
    X = controller.Position.X,
    Y = controller.Position.Y,
    Z = controller.Position.Z,
    Yaw = ExtractYaw(controller.Rotation),
    Speed = controller.Velocity.Length(),
    Grounded = controller.IsGrounded,
};

var profile = new HumanoidCapsuleBodyProfile(
    radius: 0.28f,
    halfLength: 0.62f,    // (totalHeight / 2) - radius
    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);
    }
}

controller.FaceMoveDirection = true;
controller.RotationSpeedDegPerSec = 0;  // 0 = instant snap

controller.FaceMoveDirection = false;

controller.UseExternalFacingYaw = true;
controller.ExternalFacingYaw = MathF.Atan2(
    targetPos.X - playerPos.X,
    targetPos.Z - playerPos.Z);