CharacterControllerComponent struct in Thread

Kinematic capsule for player/AI movement — wraps Jolt's CharacterVirtual. Doesn't react to forces; each frame the engine reads DesiredVelocity, runs collision/sliding/stair-stepping, and writes the resulting position back into TransformComponent.

Never put a RigidBodyComponent on the same entity. A character is one or the other. The controller carries an inner body of its own — that is what makes raycasts, triggers and overlap queries able to see the player at all — so “both” means two bodies in the same physics layer, at the same position, overlapping from the first frame. The solver has to push them apart and the direction it picks is not deterministic: the usual symptom is a character that behaves in the editor and falls through the floor in a build, or the reverse.

It is also pointless. The engine writes the controller's position into the transform and then the rigid-body pass overwrites it a few lines later, so the controller is not steering anything.

Deleting the collider is not enough. A RigidBodyComponent with no collider falls back to a default unit box, so the second body survives and nothing appears to change — remove the RigidBodyComponent. Since 0.7.0 the engine writes a warning to the log naming the entity when it finds both.

Properties — authored

RadiusfloatCapsule radius. Default 0.4.
HalfHeightfloatHalf the cylindrical body. Default 0.9.
MaxSlopeAnglefloatDegrees. Surfaces steeper than this don't count as floor. Default 45.

Properties — runtime

DesiredVelocityThread::Vec3Scripts write here each frame. Positive Y is a jump impulse; horizontal drives ground movement.
IsGroundedboolTrue when standing on something flatter than MaxSlopeAngle.
Handlevoid*Internal Jolt CharacterVirtual pointer.

Gravity policy

  • DesiredVelocity.y > 0 → treated as a jump impulse, used verbatim.
  • DesiredVelocity.y == 0 + grounded → vertical zeroed (sticks to floor).
  • DesiredVelocity.y == 0 + airborne → gravity accumulates from previous frame.

Example — first-person movement

void OnUpdate(float ts) override {
    auto& cc = GetComponent<Thread::CharacterControllerComponent>();
    float fwd   = Input::IsKeyPressed(Key::W) ? 1.0f : (Input::IsKeyPressed(Key::S) ? -1.0f : 0.0f);
    float right = Input::IsKeyPressed(Key::D) ? 1.0f : (Input::IsKeyPressed(Key::A) ? -1.0f : 0.0f);

    cc.DesiredVelocity.x =  right * 5.0f;
    cc.DesiredVelocity.z = -fwd   * 5.0f;
    if (cc.IsGrounded && Input::WasKeyPressed(Key::Space))
        cc.DesiredVelocity.y = 6.0f;
    else
        cc.DesiredVelocity.y = 0.0f;
}

CharacterControllerComponent struct w Thread

Kinematyczna kapsuła do ruchu gracza i AI — nakładka na CharacterVirtual z Jolt. Nie reaguje na siły; co klatkę silnik czyta DesiredVelocity, wykonuje kolizje, ślizganie i wchodzenie na schody, i zapisuje wynikową pozycję do TransformComponent.

Nigdy nie dawaj RigidBodyComponent na tę samą encję. Postać to jedno albo drugie. Kontroler ma własne wewnętrzne ciało — to dzięki niemu raycasty, triggery i testy nakładania w ogóle widzą gracza — więc „oba” to dwa ciała w tej samej warstwie fizyki, w tym samym miejscu, nachodzące na siebie od pierwszej klatki. Solver musi je rozepchnąć, a kierunek nie jest deterministyczny: typowy objaw to postać, która w edytorze działa, a w buildzie przelatuje przez podłogę, albo odwrotnie.

To też nic nie daje. Silnik zapisuje pozycję kontrolera do transformu, a kilka linijek dalej pass ciał sztywnych ją nadpisuje, więc kontroler niczym nie steruje.

Usunięcie collidera nie wystarczy. RigidBodyComponent bez collidera dostaje domyślny sześcian, więc drugie ciało zostaje i nic się nie zmienia — usuń RigidBodyComponent. Od 0.7.0 silnik zapisuje w logu ostrzeżenie z nazwą encji, gdy znajdzie oba.

Właściwości — ustawiane

RadiusfloatPromień kapsuły. Domyślnie 0.4.
HalfHeightfloatPołowa części walcowej. Domyślnie 0.9.
MaxSlopeAnglefloatStopnie. Powierzchnie bardziej strome nie liczą się jako podłoga. Domyślnie 45.

Właściwości — w czasie działania

DesiredVelocityThread::Vec3Skrypty wpisują tu co klatkę. Dodatnie Y to impuls skoku; poziome składowe to ruch po ziemi.
IsGroundedboolTrue, gdy stoi na czymś łagodniejszym niż MaxSlopeAngle.
Handlevoid*Wewnętrzny wskaźnik CharacterVirtual z Jolt.

Zasady grawitacji

  • DesiredVelocity.y > 0 → impuls skoku, użyty bez zmian.
  • DesiredVelocity.y == 0 + na ziemi → pionowa składowa zerowana (trzyma się podłogi).
  • DesiredVelocity.y == 0 + w powietrzu → grawitacja kumuluje się z poprzedniej klatki.

Przykład — ruch FPP

void OnUpdate(float ts) override {
    auto& cc = GetComponent<Thread::CharacterControllerComponent>();
    float fwd   = Input::IsKeyPressed(Key::W) ? 1.0f : (Input::IsKeyPressed(Key::S) ? -1.0f : 0.0f);
    float right = Input::IsKeyPressed(Key::D) ? 1.0f : (Input::IsKeyPressed(Key::A) ? -1.0f : 0.0f);

    cc.DesiredVelocity.x =  right * 5.0f;
    cc.DesiredVelocity.z = -fwd   * 5.0f;
    if (cc.IsGrounded && Input::WasKeyPressed(Key::Space))
        cc.DesiredVelocity.y = 6.0f;
    else
        cc.DesiredVelocity.y = 0.0f;
}