KinematicCharacterBody Class
Adds character-controller behaviour to a PhysicsBodyComponent with Kinematic. Set Velocity each fixed-update frame (or call MoveAndSlide(Vector2)); the KinematicCharacterSystem slides the velocity along contact surfaces and integrates it into Position before the physics step. IsGrounded, FloorNormal, CeilingNormal, and GetSlideCollisions() are updated each tick after the step.
public class KinematicCharacterBody : Brine2D.ECS.ComponentInheritance System.Object → Component → KinematicCharacterBody
Remarks¶
Requires two KinematicCharacterSystem instances registered in DI
via AddPhysics(). Add both to the scene with
world.AddSystem<KinematicCharacterSystem>().
MoveAndCollide(Vector2) and MoveAndSlide(Vector2) are mutually exclusive per tick. When MoveAndCollide(Vector2) is queued, velocity integration is skipped for that tick.
| Properties | |
|---|---|
| CeilingAngleLimit | Maximum angle (radians) between the contact normal and the down direction for a surface to count as a ceiling. Default is 0.8 rad (~46°). Contacts whose downward dot product is less than cos(CeilingAngleLimit) are not classified as ceiling. |
| CeilingNormal | The ceiling contact normal from the last step, or System.Numerics.Vector2.Zero when none. |
| EffectiveVelocity | The slide-corrected velocity actually applied to the character this tick, in pixels per second. Unlike Velocity (the desired input), this reflects the velocity after deflection against contact surfaces. Set by the pre-physics step each tick. Useful for animation blending and air/ground speed readouts. |
| EnableDebugLogging | When true, the KinematicCharacterSystem emits per-tick diagnostic trace output for this character covering pre-deflection, slide iterations, and final position integration. Use only during debugging — disable before shipping. |
| FloorAngleLimit | Maximum angle (radians) between the contact normal and the up direction for a surface to count as a floor. Default is ~46° (0.8 rad). |
| FloorNormal | The averaged floor contact normal from the last step, or System.Numerics.Vector2.Zero when IsGrounded is false. |
| IsGrounded | true when the character is resting on a floor surface this tick. |
| IsOnCeiling | true when the character is touching a ceiling surface this tick. |
| IsOnWall | true when the character is touching a wall surface this tick. |
| IsOnWallOnly | true when the character is touching a wall but is not on the floor or ceiling this tick. |
| LastMoveAndCollideHit | The result of the last MoveAndCollide(Vector2) call, or null when there was no collision. Set by the pre-step system after processing PendingMoveAndCollide. Contains full shape-cast detail including sub-shape information on compound bodies. |
| MaxSlides | Maximum number of velocity-deflection iterations in the pre-physics slide step. Default is 3. Increase for characters that must navigate tight corners reliably. |
| MaxSpeed | Maximum speed in pixels per second the character velocity is clamped to before the slide and integration step. When zero (default), no cap is applied. |
| MotionRemainder | The unused remainder of the last MoveAndCollide(Vector2) motion vector. System.Numerics.Vector2.Zero when no collision occurred or the full motion was consumed. Available after the next pre-physics step. |
| PendingMoveAndCollide | Pending MoveAndCollide(Vector2) request set during FixedUpdate. The pre-step system consumes and clears this each tick. |
| PlatformVelocity | The linear velocity of the moving platform the character is standing on, or System.Numerics.Vector2.Zero when not on a moving platform. Updated each post-physics step. |
| PushForce | Maximum force in pixels/s² the character can apply to dynamic bodies it walks into. When zero (default), no impulse is applied to dynamic bodies. Set to a positive value to push lightweight objects away when the character contacts them. |
| SnapDistance | Maximum distance in pixels to probe downward for a floor surface when the character leaves the ground. When greater than zero, the character snaps to the floor if a solid surface is found within this distance — useful for keeping the character grounded on stairs and slopes without going airborne. Default is 0 (disabled). |
| StepHeight | Maximum height in pixels the character can automatically step up onto when walking into a ledge. When zero (default), step climbing is disabled. |
| StopOnSlope | When true, the character will not slide down a sloped floor when Velocity has no component pushing into the slope. Useful for holding a character in place on ramps without requiring friction. Default is false. |
| UpDirection | The direction the character treats as "up" for floor detection and snap-to-floor. When null (default), the direction is derived each tick from the world gravity vector — correct for standard gravity. Override this for wall-walking, ceiling-walking, or per-character gravity effects. |
| Velocity | Desired movement velocity in pixels per second. Set this every fixed-update frame. |
| WallAngleLimit | Maximum angle (radians) between the contact normal and the wall angle limit for a surface to count as a wall. Contacts that are neither floor nor ceiling and fall within this range set IsOnWall and WallNormal. Default is System.Single.PositiveInfinity (all non-floor, non-ceiling contacts qualify). |
| WallNormal | The averaged wall contact normal from the last step, or System.Numerics.Vector2.Zero when IsOnWall is false. |
| Methods | |
|---|---|
| GetSlideCollisions() | Returns all contact pairs resolved during the last post-physics step. Normals are oriented away from the other body toward this character. Useful for surface material detection, landing sounds, and wall-jump queries. The list is cleared and repopulated every tick — do not hold a reference across frames. |
| MoveAndCollide(Vector2) | Queues a discrete move for this tick. Unlike MoveAndSlide(Vector2), the character moves exactly by motion without sliding along surfaces. If a solid surface is hit during the cast, the character stops at the contact point and LastMoveAndCollideHit is set with full sub-shape detail; otherwise it is null. The result is available after the next pre-physics step. Mutually exclusive with MoveAndSlide(Vector2) per tick — velocity integration is skipped for any tick in which a MoveAndCollide(Vector2) motion is queued. |
| MoveAndSlide(Vector2) | Sets Velocity and returns this component for fluent call sites. |
| Events | |
|---|---|
| OnAirborne | Fired once when the character transitions from grounded to airborne. Invoked at the end of the post-physics step, after IsGrounded is set. |
| OnLanded | Fired once when the character transitions from airborne to grounded. Invoked at the end of the post-physics step, after IsGrounded is set. |