walk

The walk component controls character movement and animations.
It supports walking, sprinting, turning styles, auto-walk, and point-and-click movement.

⚠️ Project setup required

The walk component relies on A-Frame, ammo.js and the physics system, which must be loaded as UMD globals before use. Follow Game components — Setup to prepare a fresh project before continuing.

Import

Once the project setup is in place, side-effect import the component so it self-registers on AFRAME:

import "spatial-design-system/components/game/walk.js";

Example: `smoothTurn` turn type

The character rotates smoothly while moving.

html


<a-entity
  walk="
    turnType: smoothTurn;
  "
></a-entity>

See Quick Start section for all movement customization options.
See Scene setup section for how to set up the scene and entities.

Example: `stepTurnDiagonal` turn type

The character rotates to 8 directions (↑, ↗, →, ↘, ↓, ↙, ←, ↖) before moving.

html


<a-entity
  walk="
    turnType: stepTurnDiagonal;
  "
></a-entity>

See Quick Start section for all movement customization options.
See Scene setup section for how to set up the scene and entities.

Quick start (How it works)

Movement Type (`turnType`):

smoothTurn: Smooth rotation while moving.
stepTurnCardinal: Rotation to 4 directions (↑, →, ↓, ←)
stepTurnDiagonal: Rotation to 8 directions (↑, ↗, →, ↘, ↓, ↙, ←, ↖)
default value: smoothTurn

html

<a-entity
  walk="
    turnType: smoothTurn;
  "
></a-entity>

Point-and-click movement:

targetWalk: Moves the character to the clicked location (default value: false).

html

<a-entity
  walk="
    targetWalk: true;
  "
></a-entity>

Auto-walk:

autoWalk: Automatically starts walking forward without input (default value: false).
- It can be combined with any movement types.

html

<a-entity
  walk="
    autoWalk: true;
  "
></a-entity>

Sprint:

sprint: Enables sprinting (default value: false).
sprintSpeed: Speed while sprinting (default value: 6).
keySprint: Key for sprinting (default value: shift).

html

<a-entity
  walk="
    sprint: true;
    sprintSpeed: 6;
    keySprint: shift;
  "
></a-entity>

Animations:

walkClipName: Animation name for walking (default value: Walk)
idleClipName: Animation name for idle (default value: Idle)

html

<a-entity
  walk="
    walkClipName: Walk;
    idleClipName: Idle;
  "
></a-entity>

sprintClipName: Animation name for sprinting (default value: Gallop)
- NOTE: you need to enable sprint (default value is false)

html

<a-entity
  walk="
    sprintClipName: Gallop;
    sprint: true;
  "
></a-entity>

Speed:

speed: Movement (default value: 3)
rotationSpeed: Turning speed
- default value: 90 (optimal for smoothTurn)
- recommended value: 450 (optimal for targetWalk)
- recommended value: 600 (optimal for stepTurnCardinal and stepTurnDiagonal)

html

<a-entity
  walk="
    speed: 3;
    rotationSpeed: 90;
  "
></a-entity>

Controls:

keyUp: Key for moving forward (default value: w)
keyDown: Key for moving backward (default value: s)
keyLeft: Key for moving left (default value: a)
keyRight: Key for moving right (default value: d)

html

<a-entity
  walk="
    keyUp: w;
    keyDown: s;
    keyLeft: a;
    keyRight: d;
  "
></a-entity>

Fix Orientation:

forwardOffsetAngle: Applies an angle correction to fix the model's forward orientation (default value: 0).

html

  
<a-entity
  walk="
    forwardOffsetAngle: 90;
  "
></a-entity>

Scene setup

Use parent (logic) + child (visual) structure.
- Parent → walk + physics
- Child → model + shape
- See Parent + Child Structure section for more details.
Camera usage:
- Use the id for camera targeting (see game-view documentation).

import "spatial-design-system/components/game/walk.js";

html


<a-scene>
  <a-entity
    walk="
          walkClipName: Walk; 
          idleClipName: Idle; 
        "
    id="fox-character"
    ammo-body="type: dynamic; angularFactor: 0 0 0; mass: 20; activationState: disableDeactivation"
    position="0 1.8 0">
    <a-entity gltf-model="#fox" ammo-shape="type: hull;" position="0 -1.3 0.2" scale="1 1 1"></a-entity>
  </a-entity>
</a-scene>

forwardOffsetAngle

In some 3D models, the visual forward direction (the way the model appears to face) may not align with its logical forward axis (the direction considered "forward" in the game world). This misalignment can lead to confusion when controlling the character, as the movement direction may not match the player's expectations based on the model's appearance. To fix this, you can use the forwardOffsetAngle property.

The forwardOffsetAngle property allows you to specify an angular offset (in degrees) that defines how much the model’s logical forward direction differs from its visual forward axis. By setting this property, you can ensure that when the player moves the character forward, it moves in the direction that visually makes sense based on the model's orientation.

For example, imagine you have a fox model placed in the game world. When you press the forward movement key, you expect the fox to walk in the direction it’s visually facing. However, it moves backward, behind the tail instead. To fix this, set the forwardOffsetAngle to 180 degrees to align the logical forward movement with the fox’s visual direction.

html


<a-entity
  walk="
    forwardOffsetAngle: 90;
  "
></a-entity>

Props

Property	Type	Default	Description
walkClipName	string	Walk	Name of the animation clip used when the character is walking.
idleClipName	string	Idle	Name of the animation clip used when the character is idle.
sprintClipName	string	Gallop	Name of the animation clip used when the character is sprinting.
turnType	enum(smoothTurn, stepTurnCardinal, stepTurnDiagonal)	smoothTurn	Defines the walking mode and how the player turns and moves.
autoWalk	boolean	false	If true, the player will automatically start walking forward without input.
targetWalk	boolean	false	If true, enables point-and-click movement: the character walks toward the location where the player clicks.
speed	number	5.0	Defines the player's base walking speed.
rotationSpeed	number	90.0	Defines the turning speed for smoothTurn mode.
sprint	boolean	false	If true, the player can sprint when holding the keySprint, increasing their speed to sprintSpeed.
keySprint	string	shift	Key used to sprint with the character.
sprintSpeed	number	8.0	Defines the sprinting speed when the sprint mode is active.
keyUp	string	w	Key used to move the character forward.
keyDown	string	s	Key used to move the character backward.
keyLeft	string	a	Key used to move the character left.
keyRight	string	d	Key used to move the character right.
startMovingDirection	enum (up, down, left, right)	down	Defines the initial logical direction for step turns. Important for alignment in grid-based movement.
forwardOffsetAngle	number	0	The angular offset (in degrees) that defines how much the model’s logical forward direction differs from its visual or model-space forward axis. In other words, it specifies how far the character’s or object’s “forward” (as understood by the user or game logic) is rotated relative to the model’s default orientation in the 3D scene.

Events

The walk component emits the following events on key movement interactions, so other components can react to character movement:

Event	Parameters	Description
walk-move-start	`{ direction: string, speed: number, rotationSpeed?: number, targetPosition?: object }`	Emitted when the character starts moving. `direction` is one of `forward`, `backward`, `left`, `right`, or `target`. `rotationSpeed` is included for turning (`left` / `right` / `target`); `targetPosition` is included for point-and-click (`target`) movement.
walk-move-stop	`{ direction: string }`	Emitted when movement in a given direction stops.
walk-sprint-start	`{ speed: number }`	Emitted when sprinting begins. Returns the sprint speed.
walk-sprint-stop	-	Emitted when sprinting ends.

Note

You can listen to these events to drive animations, sounds, or UI from character movement.

el.addEventListener("walk-move-start", (event) => {
  console.log(event.detail.direction, event.detail.speed);
});

Parent and Child Structure

To create a functional character controller, we recommend using a parent-child structure. This separates the physics calculations from the visual representation, allowing for better control over the character's pivot point and grounding.

Parent Entity (The Logic): The main container holds the walk component and the physics body (ammo-body). It represents the character's physical presence in the world.

We set angularFactor: 0 0 0 to prevent the character from tipping over or rolling like a ball.
We use activationState: disableDeactivation to ensure the physics engine never puts the character to "sleep" when standing still.
Type dynamic allows the character to be affected by forces and collisions, making it responsive to the environment.
The mass value refer to the character's weight, which affects how it interacts with physics.
Camera usage: Assign a unique id (e.g., id="fox-character"). This ID is required for the camera to identify and follow the player. For more details on setting up the follow behavior of the camera, please refer to the game-view documentation.

Child Entity (The Visual): This entity contains the 3D model (gltf-model) and the physics shape (ammo-shape).

You often need to adjust the child's position (e.g., y: -1.3) to ensure the model's feet touch the ground, as the parent physics body is usually centered at its middle point.

html


<a-scene>
  <a-entity
    walk="
          walkClipName: Walk; 
          idleClipName: Idle; 
        "
    id="fox-character"
    ammo-body="type: dynamic; angularFactor: 0 0 0; mass: 20; activationState: disableDeactivation"
    position="0 1.8 0">
    <a-entity gltf-model="#fox" ammo-shape="type: hull;" position="0 -1.3 0.2" scale="1 1 1"></a-entity>
  </a-entity>
</a-scene>

Credits & 3D Models Attribution

The project utilizes 3D assets from Poly.pizza. Below is the attribution for each model used in the games.

Creative Commons Attribution (CC BY)

The following model requires attribution to the original creator as per the CC BY 3.0 license.

Model Name	Author
Zombie	bachosoftdesign
Tree, Tree-2	Marc Solà
Cave Scene	Brandon Jones (Toji)
Mountain	Servin Nissen
Pond	jeremy
Jeep	Zsky
Rabbit	Sherkiz
Bush	Jarlan Perez
Pine Tree	Danni Bittman

Public Domain (CC0)

The following model is provided under the CC0 1.0 license (Public Domain).

Model Name	Author
Adventurer, Frog, Stag, Rocks, Shiba Inu, Bear Trap	Quaternius

Attaching to physical world

Appearance

Behavior

Menu Type

walk

Import

Example: `smoothTurn` turn type

Example: `stepTurnDiagonal` turn type

Quick start (How it works)

Movement Type (`turnType`):

Point-and-click movement:

Auto-walk:

Sprint:

Animations:

Speed:

Controls:

Fix Orientation:

Scene setup

forwardOffsetAngle

Props

Events

Parent and Child Structure

Credits & 3D Models Attribution

Creative Commons Attribution (CC BY)

Public Domain (CC0)

walk ​

Import ​

Example: smoothTurn turn type ​

Example: stepTurnDiagonal turn type ​

Quick start (How it works) ​

Movement Type (turnType): ​

Point-and-click movement: ​

Auto-walk: ​

Sprint: ​

Animations: ​

Speed: ​

Controls: ​

Fix Orientation: ​

Scene setup ​

forwardOffsetAngle ​

Props ​

Events ​

Parent and Child Structure ​

Credits & 3D Models Attribution ​

Creative Commons Attribution (CC BY) ​

Public Domain (CC0) ​

walk

Import

Example: `smoothTurn` turn type

Example: `stepTurnDiagonal` turn type

Quick start (How it works)

Movement Type (`turnType`):

Point-and-click movement:

Auto-walk:

Sprint:

Animations:

Speed:

Controls:

Fix Orientation:

Scene setup

forwardOffsetAngle

Props

Events

Parent and Child Structure

Credits & 3D Models Attribution

Creative Commons Attribution (CC BY)

Public Domain (CC0)