Three.js Blocks

Home
Documentation
Examples
Tools

KinematicBody

@three-blocks/proPhysicsBodyNPCWebGPUWebGL
new KinematicBody(views : Object, type : string, index : number, entity : THREE.Object3D|null, physics : Object)
Extends
Body

Kinematic Body - Body with Navigation Support

Extends Body with navigation capabilities for kinematic physics bodies. Provides intuitive API for NPC navigation with obstacle avoidance.

Features

  • A* pathfinding with octile heuristic (when grid enabled)
  • Basic straight-line navigation (no grid required)
  • Local obstacle avoidance using BVH raycasts
  • Automatic path replanning when blocked
  • Promise-based navigation with arrival callbacks

Usage

Constructor Parameters
viewsObject
Physics views object containing type-indexed body arrays.
typestring
Body type (should be 'kinematic').
indexnumber
Body index in the views array.
entityTHREE.Object3D | null
Optional entity to sync transforms to.
physicsObject
Physics instance for worker communication.
Example
const npc = await physics.addBody(BodyType.KINEMATIC, mesh);

// Enable A* navigation with grid
await npc.body.navigation.enable(grid, { maxSpeed: 5, arrivalRadius: 1.5 });

// Navigate to position
await npc.body.navigation.navigateTo(targetPosition);

// Or with callback
npc.body.navigation.navigateTo(targetPosition, () => console.log('Arrived!'));

// Check state
if (npc.body.navigation.isNavigating) { ... }
if (npc.body.navigation.hasArrived) { ... }

// Stop navigation
npc.body.navigation.stop();

Properties

.isKinematicBody : boolean

Three.js-style type flag. True for KinematicBody instances.

.isNavigating : boolean

Check if currently navigating.

.pathfindingEnabled : boolean

Check if navigation was enabled.

.destination : THREE.Vector3|null

Get current destination (if navigating).

.agent : Agent

Agent configuration interface.

Provides immediate sync of pathfinding parameters to the physics worker. Changes to properties are applied instantly without requiring re-initialization.

.ai : AIAgent

AI agent interface for adding sensors and intents.

Provides a Three.js-style API for configuring AI behavior.

.navigation : Navigation

Navigation interface for pathfinding.

Provides BASIC (straight-line) and A* pathfinding navigation. BASIC mode requires no setup - just call navigateTo(). A* mode requires a PathfindingGrid via enable().

.pathfinder : Navigation

Alias for navigation (backwards compatibility).

.camera :

Get camera instance for this body. Used for spectating and multiplayer scenarios.

.camera :

Set camera instance for this body.

Methods

enablePathfinding#

enablePathfinding(config : Object) : Promise<boolean>

Enable pathfinding for this body.

Parameters
configoptionalObject
Pathfinding configuration.
Default is {}.
  • maxSpeedoptionalnumber
    Maximum movement speed.
    Default is 5.0.
  • arrivalRadiusoptionalnumber
    Distance to consider arrived.
    Default is 1.5.
  • avoidanceRadiusoptionalnumber
    Obstacle avoidance radius.
    Default is 1.5.
  • replanThresholdoptionalnumber
    Time blocked before replanning.
    Default is 5.0.
Returns
Promise<boolean> — Success status.

navigateTo#

navigateTo(destination : THREE.Vector3|Object, onArrived : function) : Promise<boolean>

Navigate to a destination.

Parameters
destinationTHREE.Vector3 | Object
Target position.
onArrivedoptionalfunction
Optional callback when arrived.
Default is null.
Returns
Promise<boolean> — Resolves true on arrival, false on path failure.

stopNavigation#

stopNavigation() : Promise<void>

Stop current navigation.

Returns
Promise<void>

disablePathfinding#

disablePathfinding() : Promise<void>

Disable pathfinding and clean up.

Returns
Promise<void>

dispose#

dispose()

Dispose of the kinematic body, cleaning up navigation, AI, and event listeners. Called automatically by Physics.removeBody().