@djodjonx/gwen-plugin-physics2d

2D physics plugin for GWEN (Rapier2D + WASM).

This documentation is plugin-specific, not engine-wide.

Installation

pnpm add @djodjonx/gwen-plugin-physics2d

Quick start

import { defineConfig } from '@djodjonx/gwen-kit';
import { physics2D } from '@djodjonx/gwen-plugin-physics2d';

export default defineConfig({
  plugins: [
    physics2D({
      gravity: -9.81,
      gravityX: 0,
      maxEntities: 10000,
      qualityPreset: 'medium',
      eventMode: 'pull',
      coalesceEvents: true,
    }),
  ],
});

What the plugin provides

• physics service (runtime API): bodies, colliders, velocity, impulses, collision batches.
• Global hooks: physics:collision, physics:collision:batch, physics:sensor:changed.
• Prefab extension extensions.physics with legacy bridge + vNext colliders[].
• Material presets: default, ice, rubber.
• Tilemap helpers and chunk streaming runtime.
• Systems: createPhysicsKinematicSyncSystem() and createPlatformerGroundedSystem().

Tree-shakable imports (Sprint 8)

import { physics2D } from '@djodjonx/gwen-plugin-physics2d/core';
import { buildTilemapPhysicsChunks } from '@djodjonx/gwen-plugin-physics2d/tilemap';
import { PHYSICS_MATERIAL_PRESETS } from '@djodjonx/gwen-plugin-physics2d/debug';

Available entry points:

• @djodjonx/gwen-plugin-physics2d (full)
• @djodjonx/gwen-plugin-physics2d/core
• @djodjonx/gwen-plugin-physics2d/helpers
• @djodjonx/gwen-plugin-physics2d/tilemap
• @djodjonx/gwen-plugin-physics2d/debug

Key config options

• qualityPreset?: 'low' | 'medium' | 'high' | 'esport'
• ccdEnabled?: boolean (global fallback)
• coalesceEvents?: boolean
• eventMode?: 'pull' | 'hybrid'
• compat?: { legacyPrefabColliderProps?: boolean; legacyCollisionJsonParser?: boolean }

Recommended runtime pattern

1. Declare physics in prefabs with extensions.physics.colliders[].
2. Use physics.getCollisionEventsBatch() in gameplay systems.
3. Keep getCollisionEvents() only for legacy compatibility.
4. Use tilemap chunk helpers for large maps; patch chunks incrementally.

Prefab example (vNext)

import { definePrefab } from '@djodjonx/gwen-engine-core';

export const BulletPrefab = definePrefab({
  name: 'Bullet',
  extensions: {
    physics: {
      bodyType: 'dynamic',
      ccdEnabled: true,
      colliders: [{ shape: 'ball', radius: 4 }],
      onCollision(self, _other, contact, api) {
        if (!contact.started) return;
        api.destroyEntity(self);
      },
    },
  },
  create: (api, x: number, y: number) => {
    const id = api.createEntity();
    api.addComponent(id, 'position', { x, y });
    return id;
  },
});

Documentation index

• API: docs/API.md
• Migration: docs/MIGRATION.md
• Tilemap: docs/TILEMAP.md
• Hooks: docs/hooks.md
• Systems: docs/systems.md