Use Physics

Add realistic physics simulation with rigidbodies, colliders, and forces

Learn how to add realistic physics simulation to your Needle Engine projects using the built-in Rapier physics engine.

:::tip When to Use Physics

Realistic object movement and interactions
Gravity and falling objects
Collision detection and response
Force-based movement (explosions, wind, throwing)
Trigger zones for gameplay mechanics :::

Quick Start

Add physics to an object:

import { Behaviour, Rigidbody } from "@needle-tools/engine";

export class PhysicsExample extends Behaviour {
    start() {
        // Add a rigidbody component at runtime
        const rb = this.gameObject.addNewComponent(Rigidbody);

        // Configure physics properties
        rb.mass = 10;
        rb.drag = 0.5;
        rb.angularDrag = 0.5;

        console.log("Physics enabled!");
    }
}

:::tip Unity/Blender Setup In most cases, you'll add Rigidbody and Collider components directly in Unity or Blender, not in code. The exported glTF will include these physics components automatically. :::

Rigidbodies

Rigidbodies add physics simulation to objects. They respond to forces, gravity, and collisions.

Basic Rigidbody

import { Behaviour, Rigidbody } from "@needle-tools/engine";

export class Ball extends Behaviour {
    private rigidbody?: Rigidbody;

    awake() {
        // Get the rigidbody component
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    start() {
        if (this.rigidbody) {
            // Configure mass and drag
            this.rigidbody.mass = 5;
            this.rigidbody.drag = 0.1;
            this.rigidbody.angularDrag = 0.05;

            // Enable/disable gravity
            this.rigidbody.useGravity = true;
        }
    }
}

Rigidbody Properties

Property

Type

Description

mass

number

Mass in kilograms (default: 1)

drag

number

Linear drag (air resistance)

angularDrag

number

Rotational drag

useGravity

boolean

Apply gravity force

isKinematic

boolean

Controlled by code, not physics

lockRotation

boolean

Prevent rotation from physics

Apply Forces

Move rigidbodies using physics forces:

Impulse Force (Instant)

import { Behaviour, Rigidbody, serializable } from "@needle-tools/engine";
import { Vector3 } from "three";

export class Launcher extends Behaviour {
    @serializable()
    launchForce: number = 10;

    private rigidbody?: Rigidbody;

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    launch() {
        if (this.rigidbody) {
            // Apply instant force upward
            const force = new Vector3(0, this.launchForce, 0);
            this.rigidbody.applyImpulse(force);

            console.log("Object launched!");
        }
    }
}

Continuous Force

import { Behaviour, Rigidbody } from "@needle-tools/engine";
import { Vector3 } from "three";

export class Thruster extends Behaviour {
    private rigidbody?: Rigidbody;
    private thrust = 5;

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    update() {
        if (this.rigidbody) {
            // Apply continuous upward force
            const force = new Vector3(0, this.thrust, 0);
            this.rigidbody.applyForce(force);
        }
    }
}

Torque (Rotation)

import { Behaviour, Rigidbody } from "@needle-tools/engine";
import { Vector3 } from "three";

export class Spinner extends Behaviour {
    private rigidbody?: Rigidbody;

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    start() {
        if (this.rigidbody) {
            // Apply rotational impulse around Y axis
            const torque = new Vector3(0, 10, 0);
            this.rigidbody.applyTorque(torque);
        }
    }
}

Set Velocity Directly

Control rigidbody velocity:

import { Behaviour, Rigidbody } from "@needle-tools/engine";
import { Vector3 } from "three";

export class DirectMovement extends Behaviour {
    private rigidbody?: Rigidbody;

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    update() {
        if (this.rigidbody) {
            // Set velocity directly
            const velocity = new Vector3(0, 0, 5); // Move forward at 5 m/s
            this.rigidbody.setVelocity(velocity);

            // Set angular velocity (rotation)
            const angularVel = new Vector3(0, 1, 0); // Spin around Y axis
            this.rigidbody.setAngularVelocity(angularVel);
        }
    }

    getSpeed(): number {
        // Get current speed
        return this.rigidbody?.getVelocity().length() ?? 0;
    }
}

Kinematic Rigidbodies

Kinematic rigidbodies are controlled by code, not physics:

import { Behaviour, Rigidbody } from "@needle-tools/engine";
import { Vector3 } from "three";

export class Platform extends Behaviour {
    private rigidbody?: Rigidbody;
    private startPos = new Vector3();

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
        this.startPos.copy(this.gameObject.position);
    }

    start() {
        if (this.rigidbody) {
            // Make kinematic - controlled by code
            this.rigidbody.isKinematic = true;
        }
    }

    update() {
        // Move platform with code
        const time = this.context.time.time;
        this.gameObject.position.y = this.startPos.y + Math.sin(time) * 2;

        // Kinematic rigidbodies still affect dynamic objects!
        // Objects will ride on this platform
    }
}

:::tip Kinematic Use Cases

Moving platforms
Elevators
Doors
Character controllers
Anything that moves predictably but should affect other physics objects :::

Collision Detection

Detect when rigidbodies collide:

import { Behaviour, Collision, serializable } from "@needle-tools/engine";

export class Breakable extends Behaviour {
    @serializable()
    breakForce: number = 10;

    onCollisionEnter(col: Collision) {
        console.log("Hit by:", col.collider.gameObject.name);

        // Calculate impact force (approximate)
        const impact = this.estimateImpact(col);

        if (impact > this.breakForce) {
            console.log("Object broke from impact!");
            this.destroy();
        }
    }

    private estimateImpact(col: Collision): number {
        // Get relative velocity (simplified)
        return 5; // In real code, calculate from velocities
    }
}

Collision Events

Event

When Called

onCollisionEnter

Collision starts

onCollisionStay

Collision continues (every frame)

onCollisionExit

Collision ends

See: Physics Events Reference for complete API

Trigger Zones

Triggers detect objects without physical collision:

import { Behaviour, Collision, serializable } from "@needle-tools/engine";
import { Object3D } from "three";

export class Checkpoint extends Behaviour {
    @serializable()
    nextCheckpoint?: Object3D;

    private activated = false;

    onTriggerEnter(col: Collision) {
        if (this.activated) return;

        // Check if player entered
        const player = col.collider.gameObject.getComponent(PlayerController);
        if (player) {
            this.activated = true;
            console.log("Checkpoint reached!");
            this.onCheckpointReached(player);
        }
    }

    private onCheckpointReached(player: PlayerController) {
        // Handle checkpoint logic
        player.setSpawnPoint(this.gameObject.position);
    }
}

:::tip Trigger vs Collision

Triggers: Objects pass through (detection zones, pickups, checkpoints)
Collisions: Physical response (solid walls, bouncing balls)

Mark colliders as "Is Trigger" in Unity/Blender to make them triggers. :::

Raycasting

Check for physics objects along a ray:

import { Behaviour, RaycastOptions } from "@needle-tools/engine";
import { Vector3 } from "three";

export class Scanner extends Behaviour {
    update() {
        const origin = this.gameObject.position;
        const direction = this.gameObject.forward;

        // Raycast using physics engine (tests against colliders)
        const options: RaycastOptions = {
            maxDistance: 10,
            precise: true,  // Use collider shapes
        };

        const hits = this.context.physics.engine.raycast(origin, direction, options);

        if (hits.length > 0) {
            console.log("Found object:", hits[0].object.name);
            console.log("Distance:", hits[0].distance);
        }
    }
}

See: Perform Raycasting for complete guide

Layers and Filtering

Use layers to control what collides with what:

import { Behaviour, Rigidbody } from "@needle-tools/engine";

export class LayeredObject extends Behaviour {
    awake() {
        // Set object layer
        this.gameObject.layers.set(1); // Layer 1
    }

    start() {
        const rb = this.gameObject.getComponent(Rigidbody);
        if (rb) {
            // Configure which layers this rigidbody collides with
            // (This is typically done in Unity/Blender physics settings)
        }
    }
}

:::tip Layer Configuration Layer collision matrices are usually configured in Unity's Physics Settings or Blender's physics properties, not in code. :::

Physics Materials

Control friction and bounciness:

import { Behaviour, PhysicsMaterial } from "@needle-tools/engine";

export class BouncyBall extends Behaviour {
    start() {
        // Physics materials are typically set in Unity/Blender
        // But you can modify them at runtime:

        const collider = this.gameObject.getComponent(BoxCollider);
        if (collider?.physicsMaterial) {
            collider.physicsMaterial.bounciness = 0.9;  // Very bouncy
            collider.physicsMaterial.friction = 0.1;    // Low friction
        }
    }
}

Character Controller Example

Complete physics-based character:

import { Behaviour, Rigidbody, serializable } from "@needle-tools/engine";
import { Vector3 } from "three";

export class PhysicsCharacter extends Behaviour {
    @serializable()
    moveSpeed: number = 5;

    @serializable()
    jumpForce: number = 8;

    private rigidbody?: Rigidbody;
    private isGrounded = false;

    awake() {
        this.rigidbody = this.gameObject.getComponent(Rigidbody);
    }

    start() {
        if (this.rigidbody) {
            // Configure for character
            this.rigidbody.lockRotation = true;  // Don't fall over
            this.rigidbody.drag = 2;             // Stop quickly
        }
    }

    update() {
        if (!this.rigidbody) return;

        const input = this.context.input;
        const velocity = this.rigidbody.getVelocity();

        // Horizontal movement
        const moveX = (input.getKey("d") ? 1 : 0) - (input.getKey("a") ? 1 : 0);
        const moveZ = (input.getKey("s") ? 1 : 0) - (input.getKey("w") ? 1 : 0);

        velocity.x = moveX * this.moveSpeed;
        velocity.z = moveZ * this.moveSpeed;

        // Jump
        if (input.getKeyDown("space") && this.isGrounded) {
            velocity.y = this.jumpForce;
        }

        this.rigidbody.setVelocity(velocity);

        // Check if grounded (simplified)
        this.checkGrounded();
    }

    private checkGrounded() {
        // Use raycast to check ground
        const origin = this.gameObject.position.clone();
        origin.y += 0.1;
        const direction = new Vector3(0, -1, 0);

        const hits = this.context.physics.raycast(origin, direction, {
            maxDistance: 0.2
        });

        this.isGrounded = hits.length > 0;
    }
}

Performance Tips

Reduce Physics Updates

// Don't do this every frame:
❌ this.gameObject.getComponent(Rigidbody);

// Cache it once:
✅ awake() {
    this.rigidbody = this.gameObject.getComponent(Rigidbody);
}

Use Sleep

Physics objects automatically sleep when stationary. Don't wake them unnecessarily:

// This wakes the rigidbody:
rigidbody.setVelocity(new Vector3(0, 0, 0));

// This keeps it asleep:
if (rigidbody.getVelocity().length() > 0.1) {
    rigidbody.setVelocity(new Vector3(0, 0, 0));
}

Simplify Colliders

Use primitive colliders (box, sphere, capsule) instead of mesh colliders
Mesh colliders are much slower, use sparingly
For complex shapes, combine multiple primitive colliders

Common Issues

Object Falls Through Floor

Problem: Fast-moving objects pass through thin colliders

Solution: Enable Continuous Collision Detection (CCD) in Unity/Blender, or use thicker colliders

Physics Feels Floaty

Problem: Movement doesn't feel responsive

Solution:

Increase drag on rigidbody
Use higher gravity (configure in Unity/Blender)
Reduce mass for lighter feel

Jittery Movement

Problem: Objects vibrate or jitter

Solution:

Reduce angularDrag if spinning too much
Check for multiple overlapping colliders
Ensure colliders don't start intersecting

Next Steps

Learn more:

Perform Raycasting - Cast rays for detection
Use Lifecycle Hooks - When to run physics code
Handle User Input - Keyboard and pointer events
Browse all How-To Guides - See all task-oriented guides

Reference:

Physics Events - Collision/trigger events API
Component Reference - Built-in physics components
Rapier Physics - Underlying physics engine

PreviousUse Lifecycle Hooks Nextweb-integration

Last updated 1 day ago

hashtagQuick Start

hashtagRigidbodies

hashtagBasic Rigidbody

hashtagRigidbody Properties

hashtagApply Forces

hashtagImpulse Force (Instant)

hashtagContinuous Force

hashtagTorque (Rotation)

hashtagSet Velocity Directly

hashtagKinematic Rigidbodies

hashtagCollision Detection

hashtagCollision Events

hashtagTrigger Zones

hashtagRaycasting

hashtagLayers and Filtering

hashtagPhysics Materials

hashtagCharacter Controller Example

hashtagPerformance Tips

hashtagReduce Physics Updates

hashtagUse Sleep

hashtagSimplify Colliders

hashtagCommon Issues

hashtagObject Falls Through Floor

hashtagPhysics Feels Floaty

hashtagJittery Movement

hashtagNext Steps

Quick Start

Rigidbodies

Basic Rigidbody

Rigidbody Properties

Apply Forces

Impulse Force (Instant)

Continuous Force

Torque (Rotation)

Set Velocity Directly

Kinematic Rigidbodies

Collision Detection

Collision Events

Trigger Zones

Raycasting

Layers and Filtering

Physics Materials

Character Controller Example

Performance Tips

Reduce Physics Updates

Use Sleep

Simplify Colliders

Common Issues

Object Falls Through Floor

Physics Feels Floaty

Jittery Movement

Next Steps