Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

13.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    PhysicsComponents.ts
 * @brief   Physics component definitions for TypeScript SDK
 */

import type { Entity, Vec2 } from '../types';
import type { AnyComponentDef, ComponentData } from '../ecs/component';
import { defineBuiltin, defineComponent } from '../ecs/component';
import type { World } from '../ecs/world';

// Box2D collision filtering: a body's own layers (category) and the layers it
// collides with (mask), as named bitmasks. Bit labels come from the project's
// collision-layer settings (the `collisionLayers` source) — see the editor.
const COLLISION_FILTER_META = {
    categoryBits: { bitmask: { bits: 16, source: 'collisionLayers' }, advanced: true },
    maskBits: { bitmask: { bits: 16, source: 'collisionLayers' }, advanced: true },
} as const;

// =============================================================================
// Component Data Interfaces
// =============================================================================

export interface RigidBody2DData {
    bodyType: number;
    gravityScale: number;
    linearDamping: number;
    angularDamping: number;
    fixedRotation: boolean;
    bullet: boolean;
    enabled: boolean;
}

export interface BoxCollider2DData {
    halfExtents: Vec2;
    offset: Vec2;
    radius: number;
    density: number;
    friction: number;
    restitution: number;
    isSensor: boolean;
    enabled: boolean;
    categoryBits: number;
    maskBits: number;
}

export interface CircleCollider2DData {
    radius: number;
    offset: Vec2;
    density: number;
    friction: number;
    restitution: number;
    isSensor: boolean;
    enabled: boolean;
    categoryBits: number;
    maskBits: number;
}

export interface CapsuleCollider2DData {
    radius: number;
    halfHeight: number;
    offset: Vec2;
    density: number;
    friction: number;
    restitution: number;
    isSensor: boolean;
    enabled: boolean;
    categoryBits: number;
    maskBits: number;
}

export interface SegmentCollider2DData {
    point1: Vec2;
    point2: Vec2;
    density: number;
    friction: number;
    restitution: number;
    isSensor: boolean;
    enabled: boolean;
    categoryBits: number;
    maskBits: number;
}

export interface PolygonCollider2DData {
    vertices: Vec2[];
    radius: number;
    density: number;
    friction: number;
    restitution: number;
    isSensor: boolean;
    enabled: boolean;
    categoryBits: number;
    maskBits: number;
}

export interface ChainCollider2DData {
    points: Vec2[];
    isLoop: boolean;
    friction: number;
    restitution: number;
    categoryBits: number;
    maskBits: number;
    enabled: boolean;
}

// =============================================================================
// Body Type Enum
// =============================================================================

// Single-sourced from the C++ BodyType ES_ENUM via the generated module — the
// hand-restated `as const` copy this replaced could drift from C++.
export { BodyType } from '../wasm/wasm.generated';

// =============================================================================
// Builtin Component Instances
// =============================================================================

export const RigidBody2D = defineBuiltin<RigidBody2DData>('RigidBody2D', {
    bodyType: 2,
    gravityScale: 1.0,
    linearDamping: 0.0,
    angularDamping: 0.0,
    fixedRotation: false,
    bullet: false,
    enabled: true
}, {
    fields: {
        // bodyType's dropdown is generated from the C++ BodyType enum.
        linearDamping: { min: 0, advanced: true },
        angularDamping: { min: 0, advanced: true },
        fixedRotation: { advanced: true },
        bullet: { advanced: true },
    },
});

export const BoxCollider2D = defineBuiltin<BoxCollider2DData>('BoxCollider2D', {
    halfExtents: { x: 0.5, y: 0.5 },
    offset: { x: 0, y: 0 },
    radius: 0.05,
    density: 1.0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
}, { fields: { ...COLLISION_FILTER_META } });

export const CircleCollider2D = defineBuiltin<CircleCollider2DData>('CircleCollider2D', {
    radius: 0.5,
    offset: { x: 0, y: 0 },
    density: 1.0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
}, { fields: { ...COLLISION_FILTER_META } });

export const CapsuleCollider2D = defineBuiltin<CapsuleCollider2DData>('CapsuleCollider2D', {
    radius: 0.25,
    halfHeight: 0.5,
    offset: { x: 0, y: 0 },
    density: 1.0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
}, { fields: { ...COLLISION_FILTER_META } });

export const SegmentCollider2D = defineBuiltin<SegmentCollider2DData>('SegmentCollider2D', {
    point1: { x: -0.5, y: 0 },
    point2: { x: 0.5, y: 0 },
    density: 1.0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
}, { fields: { ...COLLISION_FILTER_META } });

export const PolygonCollider2D = defineComponent<PolygonCollider2DData>('PolygonCollider2D', {
    vertices: [
        { x: -0.5, y: -0.5 },
        { x: 0.5, y: -0.5 },
        { x: 0.5, y: 0.5 },
        { x: -0.5, y: 0.5 },
    ],
    radius: 0.0,
    density: 1.0,
    friction: 0.3,
    restitution: 0.0,
    isSensor: false,
    enabled: true,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
}, { fields: { ...COLLISION_FILTER_META } });

export const ChainCollider2D = defineComponent<ChainCollider2DData>('ChainCollider2D', {
    points: [
        { x: -1, y: 0 },
        { x: 0, y: 0.5 },
        { x: 1, y: 0 },
        { x: 0, y: -0.5 },
    ],
    isLoop: true,
    friction: 0.6,
    restitution: 0.0,
    categoryBits: 0x0001,
    maskBits: 0xFFFF,
    enabled: true,
}, { fields: { ...COLLISION_FILTER_META } });

// =============================================================================
// Collider Reads
// =============================================================================

/**
 * The collider's data, or null when the component is absent **or disabled** — a
 * disabled collider is equivalent to an absent one (no Box2D shape, nothing to
 * cast against, no debug outline), and every consumer reads it through here so
 * those answers agree. Data predating the field has no `enabled`, and stays solid.
 */
export function activeCollider<C extends AnyComponentDef>(
    world: World, entity: Entity, collider: C,
): ComponentData<C> | null {
    if (!world.has(entity, collider)) return null;
    const data = world.get(entity, collider);
    return (data as { enabled?: boolean }).enabled === false ? null : data;
}

// =============================================================================
// One-Way (One-Sided) Platform
// =============================================================================

export interface OneWayPlatform2DData {
    // Contacts survive only on this solid side; {0,1} is solid-top, pass-through below.
    // World/physics coordinates by default, body coordinates when localSpace is true.
    normal: Vec2;
    /** Rotate the normal with the physics body, including its parent's world rotation. */
    localSpace?: boolean;
    enabled: boolean;
}

// A collider modifier: put it on an entity that also has a RigidBody2D + a collider.
// Consumed by PhysicsSystem, which enables Box2D pre-solve events on the entity's
// shapes and feeds the normal to the one-way pre-solve callback.
export const OneWayPlatform2D = defineComponent<OneWayPlatform2DData>('OneWayPlatform2D', {
    normal: { x: 0, y: 1 },
    localSpace: false,
    enabled: true,
});

// =============================================================================
// Joint Components
// =============================================================================

// The joint's OWN entity is body B; `connectedEntity` is body A. So an axis or a
// limit "from A" is measured from the body the joint points at, and two zero
// anchors pin both centres to one point rather than keeping their offset.
const JOINT_ANCHORS = {
    anchorA: { tooltip: 'Where the joint attaches on the connected body, in that body\'s frame (pixels).' },
    anchorB: { tooltip: 'Where it attaches on this entity, in its own frame (pixels).' },
} as const;

export interface HingeJoint2DData {
    connectedEntity: number;
    anchorA: Vec2;
    anchorB: Vec2;
    enableMotor: boolean;
    motorSpeed: number;
    maxMotorTorque: number;
    enableLimit: boolean;
    lowerAngle: number;
    upperAngle: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const HingeJoint2D = defineComponent<HingeJoint2DData>('HingeJoint2D', {
    connectedEntity: -1,
    anchorA: { x: 0, y: 0 },
    anchorB: { x: 0, y: 0 },
    enableMotor: false,
    motorSpeed: 0,
    maxMotorTorque: 0,
    enableLimit: false,
    lowerAngle: 0,
    upperAngle: 0,
    collideConnected: false,
    enabled: true,
}, {
    entityFields: ['connectedEntity'],
    fields: { ...JOINT_ANCHORS,
    },
});

export interface DistanceJoint2DData {
    connectedEntity: number;
    anchorA: Vec2;
    anchorB: Vec2;
    length: number;
    enableSpring: boolean;
    hertz: number;
    dampingRatio: number;
    enableLimit: boolean;
    minLength: number;
    maxLength: number;
    enableMotor: boolean;
    maxMotorForce: number;
    motorSpeed: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const DistanceJoint2D = defineComponent<DistanceJoint2DData>('DistanceJoint2D', {
    connectedEntity: -1,
    anchorA: { x: 0, y: 0 },
    anchorB: { x: 0, y: 0 },
    length: 1,
    enableSpring: false,
    hertz: 1,
    dampingRatio: 0.5,
    enableLimit: false,
    minLength: 0.5,
    maxLength: 2,
    enableMotor: false,
    maxMotorForce: 0,
    motorSpeed: 0,
    collideConnected: false,
    enabled: true,
}, {
    entityFields: ['connectedEntity'],
    fields: { ...JOINT_ANCHORS,
    },
});

export interface SliderJoint2DData {
    connectedEntity: number;
    anchorA: Vec2;
    anchorB: Vec2;
    axis: Vec2;
    enableSpring: boolean;
    hertz: number;
    dampingRatio: number;
    enableLimit: boolean;
    lowerTranslation: number;
    upperTranslation: number;
    enableMotor: boolean;
    maxMotorForce: number;
    motorSpeed: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const SliderJoint2D = defineComponent<SliderJoint2DData>('SliderJoint2D', {
    connectedEntity: -1,
    anchorA: { x: 0, y: 0 },
    anchorB: { x: 0, y: 0 },
    axis: { x: 1, y: 0 },
    enableSpring: false,
    hertz: 1,
    dampingRatio: 0.5,
    enableLimit: false,
    lowerTranslation: 0,
    upperTranslation: 0,
    enableMotor: false,
    maxMotorForce: 0,
    motorSpeed: 0,
    collideConnected: false,
    enabled: true,
}, {
    entityFields: ['connectedEntity'],
    fields: { ...JOINT_ANCHORS,
    axis: { tooltip: 'Direction of travel, in the connected body\'s frame.' },
    },
});

export interface FixedJoint2DData {
    connectedEntity: number;
    anchorA: Vec2;
    anchorB: Vec2;
    linearHertz: number;
    angularHertz: number;
    linearDampingRatio: number;
    angularDampingRatio: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const FixedJoint2D = defineComponent<FixedJoint2DData>('FixedJoint2D', {
    connectedEntity: -1,
    anchorA: { x: 0, y: 0 },
    anchorB: { x: 0, y: 0 },
    linearHertz: 0,
    angularHertz: 0,
    linearDampingRatio: 1,
    angularDampingRatio: 1,
    collideConnected: false,
    enabled: true,
}, {
    entityFields: ['connectedEntity'],
    fields: { ...JOINT_ANCHORS,
    },
});

export interface WheelJoint2DData {
    connectedEntity: number;
    anchorA: Vec2;
    anchorB: Vec2;
    axis: Vec2;
    enableSpring: boolean;
    hertz: number;
    dampingRatio: number;
    enableLimit: boolean;
    lowerTranslation: number;
    upperTranslation: number;
    enableMotor: boolean;
    maxMotorTorque: number;
    motorSpeed: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const WheelJoint2D = defineComponent<WheelJoint2DData>('WheelJoint2D', {
    connectedEntity: -1,
    anchorA: { x: 0, y: 0 },
    anchorB: { x: 0, y: 0 },
    axis: { x: 0, y: 1 },
    enableSpring: true,
    hertz: 5,
    dampingRatio: 0.7,
    enableLimit: false,
    lowerTranslation: 0,
    upperTranslation: 0,
    enableMotor: false,
    maxMotorTorque: 0,
    motorSpeed: 0,
    collideConnected: false,
    enabled: true,
}, {
    entityFields: ['connectedEntity'],
    fields: { ...JOINT_ANCHORS,
    axis: { tooltip: 'Direction of travel, in the connected body\'s frame.' },
    },
});

export interface MotorJoint2DData {
    connectedEntity: number;
    // Target relative linear velocity (world units/s) and the max force to reach it.
    linearVelocity: Vec2;
    maxVelocityForce: number;
    // Target relative angular velocity (rad/s) and the max torque to reach it.
    angularVelocity: number;
    maxVelocityTorque: number;
    // Optional spring position control (0 hertz = velocity-only motor).
    linearHertz: number;
    linearDampingRatio: number;
    maxSpringForce: number;
    angularHertz: number;
    angularDampingRatio: number;
    maxSpringTorque: number;
    collideConnected: boolean;
    enabled: boolean;
}

export const MotorJoint2D = defineComponent<MotorJoint2DData>('MotorJoint2D', {
    connectedEntity: -1,
    linearVelocity: { x: 0, y: 0 },
    maxVelocityForce: 0,
    angularVelocity: 0,
    maxVelocityTorque: 0,
    linearHertz: 0,
    linearDampingRatio: 0,
    maxSpringForce: 0,
    angularHertz: 0,
    angularDampingRatio: 0,
    maxSpringTorque: 0,
    collideConnected: false,
    enabled: true,
}, { entityFields: ['connectedEntity'] });