DynamicBody
new DynamicBody(views : Object, type : string, index : number, entity : THREE.Object3D|null, physics : Object)DynamicBody - Physics body with Navigation Support
Extends Body with navigation capabilities for dynamic (player) physics bodies. Provides the same navigation API as KinematicBody for consistent usage.
Features
- BASIC navigation (straight-line movement, no grid)
- A* pathfinding with PathfindingGrid
- Promise-based navigation with arrival callbacks
- Three.js-style type flags
Usage
Constructor Parameters
viewsObjecttypestringindexnumberentityTHREE.Object3D | nullphysicsObjectExample
const playerResult = await physics.addBody(BodyType.DYNAMIC, playerMesh);
const playerBody = playerResult.body;
// BASIC navigation - no grid needed
playerBody.navigation.navigateTo(clickPosition);
// Or with A* pathfinding
const grid = new PathfindingGrid({ bounds });
await grid.init(physics);
await grid.compile();
await playerBody.navigation.enable(grid);
playerBody.navigation.navigateTo(clickPosition);
Properties
# .isDynamicBody : boolean
Three.js-style type flag. True for DynamicBody instances.
# .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.
# .collidesWithDynamic : boolean
Whether this body collides with other dynamic bodies.
Enabled by default. Disable for performance optimization when Dynamic ↔ Dynamic collision is not needed for specific bodies.
# .is2D : boolean
2D platformer mode flag.
When enabled, the body is constrained to move only on the X+Y plane:
- X axis: left/right movement
- Y axis: jump/gravity
- Z axis: locked (no movement)
Use for side-scrolling platformer games like Mario.
# .collisionType : number
Collision type for Dynamic ↔ Dynamic collision detection.
Controls the algorithm used for detecting collisions between dynamic bodies. Use BodyCollisionType constants or set to AUTO for automatic detection.
Performance (fastest to most accurate):
- BodyCollisionType.SPHERE: O(1) - SDF sphere-sphere test
- BodyCollisionType.CAPSULE: O(1) - SDF capsule-capsule test
- BodyCollisionType.BOX: O(log n) - BVH-to-Box collision
- BodyCollisionType.FULL: O(n log n) - Full BVH-to-BVH collision
# .contactSkin : number
Contact skin margin for ground detection.
Expands the ground detection radius beyond actual penetration to maintain
stable ground contact. Prevents Y velocity oscillation when resting on surfaces.
Default is 0.01 (1cm).
# .canSleep : boolean
Whether this body can automatically sleep when stationary.
When enabled, the body will automatically sleep after remaining
stationary (low velocity and position delta) for sleepDelay seconds.
Sleeping bodies skip physics calculations but can still be collided
with and woken up by active bodies.
Default is true.
# .sleepVelocityThreshold : number
Velocity magnitude below which the body starts the sleep timer.
The body must have velocity below this threshold AND position delta
below sleepPositionThreshold to start accumulating sleep time.
Default is 0.1.
# .sleepPositionThreshold : number
Position delta magnitude below which the body starts the sleep timer.
The body must have position delta below this threshold AND velocity
below sleepVelocityThreshold to start accumulating sleep time.
Default is 0.01.
# .sleepDelay : number
Seconds of stillness required before the body sleeps.
The body must remain stationary (below velocity and position thresholds)
for this duration before entering sleep state.
Default is 0.5.
# .sleepState : number
Current sleep state of the body.
- 0 = Awake (active physics)
- 1 = Drowsy (transitioning to sleep)
- 2 = Sleeping (physics skipped)
Read-only - controlled by the physics engine. Use this for visual feedback (e.g., color-coding sleeping bodies).
# .isSleeping : boolean
Whether the body is currently sleeping.
Convenience getter that returns true when sleepState === 2.
Methods
wake#
wake()Manually wake up a sleeping body.
The body will remain awake until it becomes stationary again (if canSleep is enabled). Use this when applying external forces or when you need to ensure a body is active.
forceSleep#
forceSleep()Manually put a body to sleep.
The body will immediately enter sleep state and skip physics calculations. It will wake up when collided with by an active body or when wake() is called.
Only works if canSleep is enabled for this body.
dispose#
dispose()Dispose of the dynamic body, cleaning up navigation and event listeners. Called automatically by Physics.removeBody().