Top down
Usage guide of character.top_down: the player seen from above, isometric follow camera, pointer aim with assist, click to move, the character.motor service for dashes and staggers; settings, services, events and hooks.
Top-down character (character.top_down) #
What it is for #
The player seen from above: an isometric follow camera, movement relative to the world on move_x / move_y, aim from the pointer (or the nearest enemy in front, or the heading) and a motor other kits use to lock, push or turn the body (attacks, dashes, staggers). It owns the entity tagged player and provides character.control. For the choice between character kits and the shared hooks, see the character guide.
Turn it on #
gripforge_gamekit_install { project_id: "gkp_…", id: "character.top_down" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "character.top_down",
config: { "moveSpeed": 7, "cameraProjection": "orthographic", "aim": "pointer" } }It requires input.actions, world.ground, physics.character, physics.port and game.engine, and conflicts with character.third_person. Optional: input.scheme (click to move) and ai.navigation (routes around walls and through doors).
First example #
<!-- test: kits/game_engine/host/tests/physics_async_lot1.rs::the_top_down_character_stands_and_holds_its_state_on_its_loop --> With a floor and two walls at x = +-5.5, holding KeyD then KeyA moves the character sideways; the walls stop it before 5.5 m, the floor holds it, and it never falls through.
Settings and defaults #
| Setting | Default | Meaning |
|---|---|---|
moveSpeed / acceleration | 7 / 60 | walk speed (m/s) and how fast the body reaches it (m/s²) |
turnSpeed | 18 | turn rate of the body toward the move or aim direction, rad/s |
aim | auto | auto: the pointer when the host publishes aim.point, else the nearest enemy in front, else the heading; or pointer, move |
aimAssistRange / aimAssistCone | 7 / 100 | assist range (m) and cone (degrees) |
cameraYaw / cameraPitch | 45 / 55 | degrees around the vertical axis, and below the horizon |
cameraDistance | 22 | metres from the target |
cameraProjection | perspective | or orthographic (then cameraViewHeight is the visible world height; 0 derives it) |
cameraFov / cameraSmoothing | 0 / 0.125 | lens (0: the renderer's); follow softness in seconds (0 follows rigidly) |
cameraTargetOffset | [0, 0, 0] | moves the framed point, in world axes |
clickArrive / clickReach | 0.3 / 1.6 | click to move: stop distance, and reach before attacking or using the clicked entity |
clickPath / clickBlocked / clickRepath | navigation / straight / 0.5 | route with ai.navigation (or straight), what to do when the point is unreachable (straight or stop), replan distance |
actionLayers | {} | animation layers by action family; empty keeps the defaults |
Services, events, variables #
character.control(service):player(),position(),teleport,attach,detach.character.motor(service):aimYaw,aimTarget,face,lock,push,setSpeedFactor,moveDir.camera.top_down(service): target, yaw, pitch, distance, shake.- Events:
player.action,player.moved(10 Hz),player.pushed(dash, lunge, knockback); it listens toroom.entered. - Variables:
player.speed,camera.mode,camera.projection,camera.viewHeight,camera.fov,camera.smoothing,aim.yaw.
Hooks and modding #
Hooks character.action (mutable movement, moveScale), character.push (mutable distance, 0 means no push) and character.respawn (mutable x, y, z; reasons scene, instance, spawn), all cancellable, with the payloads of the character guide. Every setting above is moddable.
Limits #
No free look and no first-person view. Hooks run on the web and in the native player; Godot, Unity and Unreal receive the kit as files and push and place the player without them. An unbound player model is a capsule: bind a rigged hero asset.
Versions #
Kit 1.10.0 (animation layers and character.action); the camera lens, offset and smoothing keys arrived in 1.7.0 to 1.9.0; click routes with ai.navigation in 1.6.0.