@melonjs/matter-adapter 1.0.0

package/build/index.d.ts

@@ -0,0 +1,208 @@
+import * as Matter from "matter-js";
+import { type AdapterCapabilities, type BodyDefinition, type BodyShape, type Bounds, type PhysicsAdapter, type PhysicsBody, type RaycastHit, Rect, type Renderable, Vector2d, type World } from "melonjs";
+/**
+ * Minimum melonJS version this adapter requires. The PhysicsAdapter
+ * interface, `bodyDef` auto-registration, and the resolver in
+ * `Application` are part of the 19.5 work — older releases don't have
+ * the plumbing for instance-based adapters. Tracks the engine version
+ * actually shipping these APIs (will be bumped to "19.5.0" once the
+ * engine release is cut).
+ */
+export declare const REQUIRED_MELONJS_VERSION = "19.5.0";
+/**
+ * Options accepted by the {@link MatterAdapter} constructor.
+ */
+export interface MatterAdapterOptions {
+    /** initial world gravity, default `{x: 0, y: 1}` (matter-js convention) */
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Number of physics substeps per engine frame. Each call to
+     * {@link MatterAdapter.step} runs `Engine.update(engine, dt / N)`
+     * `N` times instead of one full-dt step. Increases narrow-phase
+     * accuracy at high relative velocities (break shots, projectiles)
+     * at the cost of ~N× physics CPU. Default `1` matches the legacy
+     * single-step behaviour. Values < 1 are clamped to 1.
+     */
+    subSteps?: number;
+    /**
+     * raw matter-js engine options forwarded to `Matter.Engine.create()`.
+     * Use this to tweak solver iterations, constraint accuracy, etc.
+     */
+    matterEngineOptions?: Matter.IEngineDefinition;
+}
+/**
+ * melonJS physics adapter wrapping matter-js (https://brm.io/matter-js/).
+ *
+ * Implements the full {@link PhysicsAdapter} interface so the same game
+ * code that runs on the built-in SAT physics also runs under Matter —
+ * with the upgrade in capabilities Matter brings (real rotational
+ * dynamics, restitution-based stacking, constraints, sleeping bodies,
+ * native raycasts).
+ * @example
+ * import { Application } from "melonjs";
+ * import { MatterAdapter } from "@melonjs/matter-adapter";
+ *
+ * const app = new Application(800, 600, {
+ *     parent: "screen",
+ *     physic: new MatterAdapter(),
+ * });
+ */
+export declare class MatterAdapter implements PhysicsAdapter {
+    readonly physicLabel = "matter";
+    readonly name = "@melonjs/matter-adapter";
+    readonly version: string;
+    readonly url = "https://www.npmjs.com/package/@melonjs/matter-adapter";
+    readonly capabilities: AdapterCapabilities;
+    gravity: Vector2d;
+    /**
+     * Raw matter-js namespace — escape hatch for matter-specific features
+     * the portable `PhysicsAdapter` interface doesn't cover (constraints,
+     * compound bodies, events on the Matter engine, queries, etc.).
+     *
+     * Saves you from adding a transitive `import * as Matter from "matter-js"`
+     * just to reach the factories you need. The Matter modules are accessed
+     * by the same names matter's own docs use, so examples from the
+     * matter-js docs copy-paste without renaming:
+     *
+     * ```ts
+     * const spring = adapter.matter.Constraint.create({
+     *   bodyA: a.body, bodyB: b.body, stiffness: 0.04, length: 80,
+     * });
+     * adapter.matter.Composite.add(adapter.engine.world, spring);
+     * ```
+     *
+     * Game code that touches `adapter.matter.*` is matter-only — it will
+     * not work under any other physics adapter. Use the
+     * `PhysicsAdapter` methods for anything that should stay portable.
+     * @see {@link https://brm.io/matter-js/docs/ Official matter-js documentation}
+     * for the full module reference (`Matter.Constraint`, `Matter.Composite`,
+     * `Matter.Bodies`, `Matter.Events`, `Matter.Query`, `Matter.Vector`, …).
+     */
+    readonly matter: typeof Matter;
+    /** the underlying Matter engine; exposed for advanced use cases. */
+    engine: Matter.Engine;
+    /** back-reference to the owning melonJS world (set in {@link init}). */
+    world: World;
+    /** renderable → its matter-js body */
+    private readonly bodyMap;
+    /** matter-js body → its renderable (for collision / sync) */
+    private readonly renderableMap;
+    /** per-body velocity cap (Matter has no native equivalent) */
+    private readonly velocityLimits;
+    /** per-body bodyDef hash kept for shape introspection / removeBody */
+    private readonly defMap;
+    /**
+     * Per-body gravity multiplier. matter-js 0.20 doesn't honor a
+     * body-level gravityScale, so we emulate it by applying a counter-
+     * force each step (see {@link init} `beforeUpdate`). Only stored for
+     * bodies with scale ≠ 1; the default-1 case is the hot path and we
+     * skip the map lookup entirely for it.
+     */
+    private readonly bodyGravityScale;
+    /**
+     * Offset between `renderable.pos` (top-left in melonJS convention)
+     * and `Matter.Body.position` (centroid in Matter's convention). Stored
+     * at addBody time so syncFromPhysics can place the sprite correctly.
+     */
+    private readonly posOffsets;
+    private readonly matterOptions;
+    private readonly subSteps;
+    constructor(options?: MatterAdapterOptions);
+    /**
+     * Stored references to the listeners registered in {@link init}, so
+     * {@link destroy} can `Matter.Events.off` them. Without these stored
+     * refs, a destroy/re-init cycle would leak the old listeners and
+     * dispatch every event twice on the second cycle.
+     */
+    private _matterListeners;
+    init(world: World): void;
+    destroy(): void;
+    step(dt: number): void;
+    syncFromPhysics(): void;
+    addBody(renderable: Renderable, def: BodyDefinition): MatterAdapter.Body;
+    removeBody(renderable: Renderable): void;
+    updateShape(renderable: Renderable, shapes: BodyShape[]): void;
+    getVelocity(renderable: Renderable, out?: Vector2d): Vector2d;
+    setVelocity(renderable: Renderable, v: Vector2d): void;
+    applyForce(renderable: Renderable, force: Vector2d, point?: Vector2d): void;
+    applyImpulse(renderable: Renderable, impulse: Vector2d): void;
+    setPosition(renderable: Renderable, p: Vector2d): void;
+    private invalidateContactsFor;
+    setAngle(renderable: Renderable, angle: number): void;
+    getAngle(renderable: Renderable): number;
+    setAngularVelocity(renderable: Renderable, omega: number): void;
+    getAngularVelocity(renderable: Renderable): number;
+    applyTorque(renderable: Renderable, torque: number): void;
+    setStatic(renderable: Renderable, isStatic: boolean): void;
+    setGravityScale(renderable: Renderable, scale: number): void;
+    setSensor(renderable: Renderable, isSensor: boolean): void;
+    setFrictionAir(renderable: Renderable, friction: number | {
+        x: number;
+        y: number;
+    }): void;
+    setMaxVelocity(renderable: Renderable, limit: {
+        x: number;
+        y: number;
+    }): void;
+    getMaxVelocity(renderable: Renderable): {
+        x: number;
+        y: number;
+    };
+    setCollisionType(renderable: Renderable, type: number): void;
+    setCollisionMask(renderable: Renderable, mask: number): void;
+    /**
+     * Adapter-side debug surface: the body's AABB in renderable-local
+     * coordinates. Matter tracks `body.bounds` in WORLD space; we
+     * subtract `renderable.pos` so the result matches melonJS's local-
+     * space convention (the debug plugin translates to the renderable
+     * origin before drawing, and would otherwise see the bounds drawn
+     * offset by the renderable's world position).
+     * @param renderable - the renderable whose body bounds to read
+     * @param out - destination `Bounds` (filled in place, also returned)
+     */
+    getBodyAABB(renderable: Renderable, out: Bounds): Bounds | undefined;
+    /**
+     * Adapter-side debug surface: the body's collision shapes in
+     * renderable-local coordinates. We return the original `def.shapes`
+     * array — those are the input shape definitions in local space,
+     * unchanged by matter's body transformation (rotation is baked into
+     * matter's vertices, not into our local-space defs). Read-only.
+     * @param renderable - the renderable whose body shapes to read
+     */
+    getBodyShapes(renderable: Renderable): readonly BodyShape[];
+    isGrounded(renderable: Renderable): boolean;
+    raycast(from: Vector2d, to: Vector2d): RaycastHit | null;
+    queryAABB(rect: Rect): Renderable[];
+    private _clampVelocities;
+    private _dispatchCollisions;
+    private _shapeToMatter;
+}
+/**
+ * Namespace-merged with the {@link MatterAdapter} class to expose
+ * adapter-owned types alongside the runtime API. Access via
+ * `MatterAdapter.Body`, etc.
+ */
+export declare namespace MatterAdapter {
+    /**
+     * The concrete body handle attached to `renderable.body` under
+     * {@link MatterAdapter}. Combines the raw `Matter.Body` (with all
+     * native fields — `frictionAir`, `restitution`, `friction`, `angle`,
+     * `angularVelocity`, …) with the portable melonJS helper methods
+     * (`setVelocity`, `applyImpulse`, `setStatic`, etc.) spliced on at
+     * `addBody` time.
+     *
+     * Type it explicitly when reaching for matter-native fields:
+     *
+     * ```ts
+     * (this.body as MatterAdapter.Body).frictionAir = 0.02;
+     * ```
+     *
+     * Keeps user code free of a direct `matter-js` import — the matter
+     * dependency stays behind the adapter boundary.
+     */
+    type Body = ReturnType<typeof Matter.Body.create> & PhysicsBody;
+}
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}