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
| Radius | float | Capsule radius. Default 0.4. |
| HalfHeight | float | Half the cylindrical body. Default 0.9. |
| MaxSlopeAngle | float | Degrees. Surfaces steeper than this don't count as floor. Default 45. |
Properties — runtime
| DesiredVelocity | Thread::Vec3 | Scripts write here each frame. Positive Y is a jump impulse; horizontal drives ground movement. |
| IsGrounded | bool | True when standing on something flatter than MaxSlopeAngle. |
| Handle | void* | 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
| Radius | float | Promień kapsuły. Domyślnie 0.4. |
| HalfHeight | float | Połowa części walcowej. Domyślnie 0.9. |
| MaxSlopeAngle | float | Stopnie. Powierzchnie bardziej strome nie liczą się jako podłoga. Domyślnie 45. |
Właściwości — w czasie działania
| DesiredVelocity | Thread::Vec3 | Skrypty wpisują tu co klatkę. Dodatnie Y to impuls skoku; poziome składowe to ruch po ziemi. |
| IsGrounded | bool | True, gdy stoi na czymś łagodniejszym niż MaxSlopeAngle. |
| Handle | void* | 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;
}