npc-walk

The npc-walk component controls the movement and animation of a non-player character (NPC). It lets you customize how the NPC moves — either by walking randomly within a defined area or by following a set of predefined points. The component also provides properties to fine-tune speed, rotation, and path behavior.

⚠️ PHYSICS ENGINE

The npc-walk component rely on the Ammo.js physics engine. Ensure that Ammo.js is installed in your project for proper functionality.

How it works

1. If the character has animations, set them with the walkClipName and idleClipName properties.
2. Define how the character moves by setting the type property. Learn more about movement types here.
3. Adjust movement behavior with the speed, checkHeight, pauseAtPoints, waitBeforeStart, allowRotation, and rotationSpeed properties.
4. In points mode, set the path using the points property and control how the NPC follows it with cyclePath and randomizePointsOrder. Learn more about points mode here and see the points type example.
5. In randomMoving mode, limit the movement area using the xMin, xMax, yMin, yMax, zMin, and zMax properties. Learn more about randomMoving mode here and see the randomMoving type example.

Props

Property	Type	Default	Description	Used In
walkClipName	string	Walk	Name of the animation clip used when the NPC is walking.	All types
idleClipName	string	Idle	Name of the animation clip used when the NPC is idle.	All types
speed	number	4	Movement speed of the NPC in units per second.	All types
checkHeigh	boolean	false	If checkHeight is true, the character adjusts its height to reach the target’s exact position.	All types
pauseAtPoints	number	0	Duration (in seconds) the NPC waits after reaching each point.	All types
waitBeforeStart	number	0	Delay (in seconds) before the NPC begins moving when initialized.	All types
allowRotation	boolean	true	When true, it allows the NPC to rotate smoothly in the direction of movement.	All types
rotationSpeed	number	500	Speed at which the NPC rotates toward its walking direction (degrees per second).	All types
type	enum (randomMoving, points)	randomMoving	Defines how the character moves.
points	array	[(0, 0, 0), (5, 0, 0), (5, 0, 5)]	Array of positions the NPC walks through in order.	points
cyclePath	boolean	true	If true, the NPC loops back to the first point after reaching the last one, forming a continuous cycle.	points
randomizePointsOrder	boolean	false	If true, the NPC visits defined points in a random sequence instead of the defined order.	points
xMin	number	-5	Minimum allowed position along the X-axis.	randomMoving
xMax	number	5	Maximum allowed position along the X-axis.	randomMoving
zMin	number	-5	Minimum allowed position along the Z-axis.	randomMoving
zMax	number	5	Maximum allowed position along the Z-axis.	randomMoving
yMin	number	0	Minimum allowed position along the Y-axis.	randomMoving
yMax	number	5	Maximum allowed position along the Y-axis.	randomMoving

checkHeight

The checkHeight property is defined to control whether the character should adjust its height while moving toward a target. When set to true, the character moves vertically as well, matching the target’s height. When set to false, the character moves only horizontally and keeps its current height. The default value is false.

pauseAtPoints

The pauseAtPoints property specifies the duration (in seconds) that the NPC will wait after reaching each point in its path.

waitBeforeStart

The waitBeforeStart property defines the duration (in seconds) before the NPC begins moving when it is initialized.

allowRotation

The allowRotation property determines whether the NPC is allowed to rotate smoothly in the direction of movement. When set to true, the NPC will rotate to face the direction it is moving toward. You can adjust the speed of this rotation using the rotationSpeed property.

type

• randomMoving: enables random walking within the defined range area.
• points: walking through defined points listed in the points property.

points

The points mode makes the NPC follow a predefined path made up of specific positions. These positions are set using the points property, which takes an array of coordinates such as 0 1 5, 5 1 5, 5 1 0. The first number in each triplet represents the X coordinate, the second represents the Y coordinate, and the third represents the Z coordinate. The coordinates are separated by commas.

<a-entity
  npc-walk="
    walkClipName: Walk;
    idleClipName: Idle;
    type: points;
    points: 0 1 5, 5 1 5, 5 1 0;
  "
>
</a-entity>

You can control how the NPC moves along this path with two additional properties: cyclePath and randomizePointsOrder.

The cyclePath property controls whether the NPC loops back to the first point after reaching the last one. When set to true, the NPC continuously loops through the points in order. When set to false, the NPC moves back to the first point by following the same path in reverse. By default, cyclePath is set to true.

<a-entity
  npc-walk="
    walkClipName: Walk;
    idleClipName: Idle;
    type: points;
    points: 0 1 5, 5 1 5, 5 1 0;
    cyclePath: false;
  "
>
</a-entity>

The randomizePointsOrder property lets the NPC visit the points in a random order instead of following the original sequence. When set to true, the NPC will choose points randomly from the list. The default value is false.

<a-entity
  npc-walk="
    walkClipName: Walk;
    idleClipName: Idle;
    type: points;
    points: 0 1 5, 5 1 5, 5 1 0;
    randomizePointsOrder: true;
  "
>
</a-entity>

Example: points type

import "spatial-design-system/components/game/npcWalk";
<a-asset-item id="dog" src="/models/Dog.glb"> </a-asset-item>

<a-scene>
  <a-entity
    npc-walk="
        walkClipName: Walk; 
        idleClipName: Idle; 
        type: points; 
        points: 0 1 5, 5 1 5, 5 1 0; 
        speed: 2; 
        pauseAtPoints: 2; 
        waitBeforeStart: 3;"
    id="dog-character"
    ammo-body="type: dynamic; angularFactor: 0 0 0; mass: 20; activationState: disableDeactivation"
    position="5 1.8 5" >
    <a-entity gltf-model="#dog" ammo-shape="type: hull;" position="0 -1.5 0" scale="3 3 3" ></a-entity>
  </a-entity>
</a-scene>

randomMoving

In randomMoving mode, the NPC wanders randomly within a defined area. You can set the boundaries of this area using the xMin, xMax, yMin, yMax, zMin, and zMax properties.

  <a-entity
  npc-walk="
    walkClipName: Walk;
    type: randomMoving;
    xMin: -5;
    xMax: 5;
    yMin: -5;
    yMax: 5;
    zMin: -5;
    zMax: 5;
  "
>
</a-entity>

Example: randomMoving type

import "spatial-design-system/components/game/npcWalk";

<a-scene physics=" driver: ammo; debug: true; debugDrawMode: 1;" inspector="true">
  <!-- External file -->
  <a-asset-item id="dog" src="/models/Dog.glb"> </a-asset-item>

  <!-- NPC Character -->
  <a-entity
    npc-walk="
        walkClipName: Walk; 
        idleClipName: Idle; 
        type: randomMoving; 
        xMin: -5; xMax: 5; yMin: -5; yMax: 5; zMin: -5; zMax: 5; 
        speed: 2; 
        pauseAtPoints: 2; 
        waitBeforeStart: 3;"
    id="dog-character"
    ammo-body="type: dynamic; angularFactor: 0 0 0; mass: 20; activationState: disableDeactivation"
    position="5 1.8 5" >
    <a-entity gltf-model="#dog" ammo-shape="type: hull;" position="0 -1.5 0" scale="3 3 3" ></a-entity>
  </a-entity>
</a-scene>