react-three-game 0.0.50 → 0.0.51

package/dist/index.d.ts

@@ -12,5 +12,9 @@ export type { PrefabRootRef } from './tools/prefabeditor/PrefabRoot';
 export type { Component } from './tools/prefabeditor/components/ComponentRegistry';
 export type { FieldDefinition, FieldType } from './tools/prefabeditor/components/Input';
 export type { Prefab, GameObject, ComponentData } from './tools/prefabeditor/types';
+export { gameEvents, useGameEvent, getEntityIdFromRigidBody } from './tools/prefabeditor/GameEvents';
+export type { GameEventType, GameEventMap, GameEventPayload, PhysicsEventType, PhysicsEventPayload } from './tools/prefabeditor/GameEvents';
+export { entityEvents, useEntityEvent } from './tools/prefabeditor/GameEvents';
+export type { EntityEventType, EntityEventPayload } from './tools/prefabeditor/GameEvents';
 export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
 export { TextureListViewer, ModelListViewer, SoundListViewer, SharedCanvas, } from './tools/assetviewer/page';

package/dist/index.js

@@ -12,6 +12,10 @@ export { registerComponent } from './tools/prefabeditor/components/ComponentRegi
 export { FieldRenderer, Input, Label, Vector3Input, ColorInput, StringInput, BooleanInput, SelectInput, } from './tools/prefabeditor/components/Input';
 // Prefab Editor - Styles & Utils
 export * from './tools/prefabeditor/utils';
+// Game Events (physics + custom events)
+export { gameEvents, useGameEvent, getEntityIdFromRigidBody } from './tools/prefabeditor/GameEvents';
+// Backward compatibility aliases
+export { entityEvents, useEntityEvent } from './tools/prefabeditor/GameEvents';
 // Asset Tools
 export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
 export { TextureListViewer, ModelListViewer, SoundListViewer, SharedCanvas, } from './tools/assetviewer/page';

package/dist/tools/prefabeditor/EntityEvents.d.ts

@@ -0,0 +1,54 @@
+import type { RapierRigidBody } from '@react-three/rapier';
+export type EntityEventType = 'sensor:enter' | 'sensor:exit' | 'collision:enter' | 'collision:exit';
+export interface EntityEventPayload {
+    sourceEntityId: string;
+    targetEntityId: string | null;
+    targetRigidBody: RapierRigidBody | null | undefined;
+}
+type EventHandler = (payload: EntityEventPayload) => void;
+/**
+ * Entity event system for physics interactions.
+ *
+ * Events:
+ * - sensor:enter - Fired when something enters a sensor collider
+ * - sensor:exit - Fired when something exits a sensor collider
+ * - collision:enter - Fired when a collision starts
+ * - collision:exit - Fired when a collision ends
+ */
+export declare const entityEvents: {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit(type: EntityEventType, payload: EntityEventPayload): void;
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on(type: EntityEventType, handler: EventHandler): () => void;
+    /**
+     * Unsubscribe from an event type
+     */
+    off(type: EntityEventType, handler: EventHandler): void;
+    /**
+     * Remove all subscribers (useful for cleanup)
+     */
+    clear(): void;
+};
+/**
+ * React hook to subscribe to entity events.
+ * Automatically cleans up on unmount.
+ *
+ * @example
+ * useEntityEvent('sensor:enter', (payload) => {
+ *   if (payload.sourceEntityId === 'trigger-zone') {
+ *     console.log('Player entered trigger zone!');
+ *   }
+ * });
+ */
+export declare function useEntityEvent(type: EntityEventType, handler: EventHandler, deps?: any[]): void;
+/**
+ * Helper to extract entity ID from Rapier collision data.
+ * Entity IDs are stored in RigidBody userData.
+ */
+export declare function getEntityIdFromRigidBody(rigidBody: RapierRigidBody | null | undefined): string | null;
+export {};

package/dist/tools/prefabeditor/EntityEvents.js

@@ -0,0 +1,85 @@
+import { useEffect, useCallback } from 'react';
+// Internal subscriber storage
+const subscribers = new Map();
+/**
+ * Entity event system for physics interactions.
+ *
+ * Events:
+ * - sensor:enter - Fired when something enters a sensor collider
+ * - sensor:exit - Fired when something exits a sensor collider
+ * - collision:enter - Fired when a collision starts
+ * - collision:exit - Fired when a collision ends
+ */
+export const entityEvents = {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit(type, payload) {
+        const handlers = subscribers.get(type);
+        if (handlers) {
+            handlers.forEach(handler => {
+                try {
+                    handler(payload);
+                }
+                catch (e) {
+                    console.error(`Error in entityEvents handler for ${type}:`, e);
+                }
+            });
+        }
+    },
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on(type, handler) {
+        if (!subscribers.has(type)) {
+            subscribers.set(type, new Set());
+        }
+        subscribers.get(type).add(handler);
+        return () => {
+            var _a;
+            (_a = subscribers.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+        };
+    },
+    /**
+     * Unsubscribe from an event type
+     */
+    off(type, handler) {
+        var _a;
+        (_a = subscribers.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+    },
+    /**
+     * Remove all subscribers (useful for cleanup)
+     */
+    clear() {
+        subscribers.clear();
+    }
+};
+/**
+ * React hook to subscribe to entity events.
+ * Automatically cleans up on unmount.
+ *
+ * @example
+ * useEntityEvent('sensor:enter', (payload) => {
+ *   if (payload.sourceEntityId === 'trigger-zone') {
+ *     console.log('Player entered trigger zone!');
+ *   }
+ * });
+ */
+export function useEntityEvent(type, handler, deps = []) {
+    const stableHandler = useCallback(handler, deps);
+    useEffect(() => {
+        return entityEvents.on(type, stableHandler);
+    }, [type, stableHandler]);
+}
+/**
+ * Helper to extract entity ID from Rapier collision data.
+ * Entity IDs are stored in RigidBody userData.
+ */
+export function getEntityIdFromRigidBody(rigidBody) {
+    var _a;
+    if (!rigidBody)
+        return null;
+    const userData = rigidBody.userData;
+    return (_a = userData === null || userData === void 0 ? void 0 : userData.entityId) !== null && _a !== void 0 ? _a : null;
+}

package/dist/tools/prefabeditor/GameEvents.d.ts

@@ -0,0 +1,126 @@
+import type { RapierRigidBody } from '@react-three/rapier';
+/** Physics event types (built-in) */
+export type PhysicsEventType = 'sensor:enter' | 'sensor:exit' | 'collision:enter' | 'collision:exit';
+/** Payload for physics events */
+export interface PhysicsEventPayload {
+    sourceEntityId: string;
+    targetEntityId: string | null;
+    targetRigidBody: RapierRigidBody | null | undefined;
+}
+/**
+ * Register your custom event types here by extending this interface:
+ *
+ * declare module 'react-three-game' {
+ *   interface GameEventMap {
+ *     'player:death': { playerId: string; cause: string };
+ *     'score:change': { delta: number; total: number };
+ *   }
+ * }
+ */
+export interface GameEventMap {
+    'sensor:enter': PhysicsEventPayload;
+    'sensor:exit': PhysicsEventPayload;
+    'collision:enter': PhysicsEventPayload;
+    'collision:exit': PhysicsEventPayload;
+}
+/** All registered event types */
+export type GameEventType = keyof GameEventMap | (string & {});
+/** Get payload type for an event, or fallback to generic */
+export type GameEventPayload<T extends string> = T extends keyof GameEventMap ? GameEventMap[T] : Record<string, unknown>;
+type EventHandler<T = unknown> = (payload: T) => void;
+/**
+ * Game event system for all game interactions.
+ *
+ * Built-in physics events:
+ * - sensor:enter - Something entered a sensor collider
+ * - sensor:exit - Something exited a sensor collider
+ * - collision:enter - A collision started
+ * - collision:exit - A collision ended
+ *
+ * Custom events:
+ * - Emit any event type with any payload
+ * - Extend GameEventMap interface for type safety
+ *
+ * @example
+ * // Physics events (typed)
+ * gameEvents.emit('sensor:enter', { sourceEntityId: 'zone', targetEntityId: 'player', targetRigidBody: rb });
+ *
+ * // Custom events
+ * gameEvents.emit('player:death', { playerId: 'p1', cause: 'lava' });
+ * gameEvents.emit('level:complete', { levelId: 3, time: 45.2 });
+ */
+export declare const gameEvents: {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<T extends string>(type: T, payload: GameEventPayload<T>): void;
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): () => void;
+    /**
+     * Unsubscribe from an event type
+     */
+    off<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): void;
+    /**
+     * Remove all subscribers (useful for cleanup/reset)
+     */
+    clear(): void;
+    /**
+     * Check if an event type has any subscribers
+     */
+    hasListeners(type: string): boolean;
+};
+/**
+ * React hook to subscribe to game events.
+ * Automatically cleans up on unmount.
+ *
+ * @example
+ * // Physics event
+ * useGameEvent('sensor:enter', (payload) => {
+ *   if (payload.sourceEntityId === 'coin') collectCoin();
+ * }, []);
+ *
+ * // Custom event
+ * useGameEvent('player:death', (payload) => {
+ *   showGameOver(payload.cause);
+ * }, []);
+ */
+export declare function useGameEvent<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>, deps?: unknown[]): void;
+/**
+ * Helper to extract entity ID from Rapier collision data.
+ * Entity IDs are stored in RigidBody userData.
+ */
+export declare function getEntityIdFromRigidBody(rigidBody: RapierRigidBody | null | undefined): string | null;
+/** @deprecated Use gameEvents instead */
+export declare const entityEvents: {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<T extends string>(type: T, payload: GameEventPayload<T>): void;
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): () => void;
+    /**
+     * Unsubscribe from an event type
+     */
+    off<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): void;
+    /**
+     * Remove all subscribers (useful for cleanup/reset)
+     */
+    clear(): void;
+    /**
+     * Check if an event type has any subscribers
+     */
+    hasListeners(type: string): boolean;
+};
+/** @deprecated Use useGameEvent instead */
+export declare const useEntityEvent: typeof useGameEvent;
+/** @deprecated Use GameEventType instead */
+export type EntityEventType = PhysicsEventType;
+/** @deprecated Use PhysicsEventPayload instead */
+export type EntityEventPayload = PhysicsEventPayload;
+export {};

package/dist/tools/prefabeditor/GameEvents.js

@@ -0,0 +1,119 @@
+import { useEffect, useCallback } from 'react';
+// Internal subscriber storage
+const subscribers = new Map();
+/**
+ * Game event system for all game interactions.
+ *
+ * Built-in physics events:
+ * - sensor:enter - Something entered a sensor collider
+ * - sensor:exit - Something exited a sensor collider
+ * - collision:enter - A collision started
+ * - collision:exit - A collision ended
+ *
+ * Custom events:
+ * - Emit any event type with any payload
+ * - Extend GameEventMap interface for type safety
+ *
+ * @example
+ * // Physics events (typed)
+ * gameEvents.emit('sensor:enter', { sourceEntityId: 'zone', targetEntityId: 'player', targetRigidBody: rb });
+ *
+ * // Custom events
+ * gameEvents.emit('player:death', { playerId: 'p1', cause: 'lava' });
+ * gameEvents.emit('level:complete', { levelId: 3, time: 45.2 });
+ */
+export const gameEvents = {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit(type, payload) {
+        const handlers = subscribers.get(type);
+        if (handlers) {
+            handlers.forEach(handler => {
+                try {
+                    handler(payload);
+                }
+                catch (e) {
+                    console.error(`Error in gameEvents handler for ${type}:`, e);
+                }
+            });
+        }
+    },
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on(type, handler) {
+        if (!subscribers.has(type)) {
+            subscribers.set(type, new Set());
+        }
+        subscribers.get(type).add(handler);
+        return () => {
+            var _a;
+            (_a = subscribers.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+        };
+    },
+    /**
+     * Unsubscribe from an event type
+     */
+    off(type, handler) {
+        var _a;
+        (_a = subscribers.get(type)) === null || _a === void 0 ? void 0 : _a.delete(handler);
+    },
+    /**
+     * Remove all subscribers (useful for cleanup/reset)
+     */
+    clear() {
+        subscribers.clear();
+    },
+    /**
+     * Check if an event type has any subscribers
+     */
+    hasListeners(type) {
+        var _a, _b;
+        return ((_b = (_a = subscribers.get(type)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0) > 0;
+    }
+};
+/**
+ * React hook to subscribe to game events.
+ * Automatically cleans up on unmount.
+ *
+ * @example
+ * // Physics event
+ * useGameEvent('sensor:enter', (payload) => {
+ *   if (payload.sourceEntityId === 'coin') collectCoin();
+ * }, []);
+ *
+ * // Custom event
+ * useGameEvent('player:death', (payload) => {
+ *   showGameOver(payload.cause);
+ * }, []);
+ */
+export function useGameEvent(type, handler, deps = []) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const stableHandler = useCallback(handler, deps);
+    useEffect(() => {
+        return gameEvents.on(type, stableHandler);
+    }, [type, stableHandler]);
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Helper to extract entity ID from Rapier collision data.
+ * Entity IDs are stored in RigidBody userData.
+ */
+export function getEntityIdFromRigidBody(rigidBody) {
+    var _a;
+    if (!rigidBody)
+        return null;
+    const userData = rigidBody.userData;
+    return (_a = userData === null || userData === void 0 ? void 0 : userData.entityId) !== null && _a !== void 0 ? _a : null;
+}
+// ============================================================================
+// Backward Compatibility Aliases
+// ============================================================================
+/** @deprecated Use gameEvents instead */
+export const entityEvents = gameEvents;
+/** @deprecated Use useGameEvent instead */
+export const useEntityEvent = useGameEvent;

package/dist/tools/prefabeditor/components/PhysicsComponent.js

@@ -11,8 +11,9 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { jsx as _jsx } from "react/jsx-runtime";
 import { RigidBody } from "@react-three/rapier";
-import { useRef, useEffect } from 'react';
+import { useRef, useEffect, useCallback } from 'react';
 import { FieldRenderer } from "./Input";
+import { gameEvents, getEntityIdFromRigidBody } from "../GameEvents";
 const physicsFields = [
     {
         name: 'type',
@@ -76,12 +77,17 @@ const physicsFields = [
         label: 'Gravity Scale',
         step: 0.1,
     },
+    {
+        name: 'sensor',
+        type: 'boolean',
+        label: 'Sensor (Trigger Only)',
+    },
 ];
 function PhysicsComponentEditor({ component, onUpdate }) {
     return (_jsx(FieldRenderer, { fields: physicsFields, values: component.properties, onChange: (props) => onUpdate(Object.assign(Object.assign({}, component), { properties: Object.assign(Object.assign({}, component.properties), props) })) }));
 }
 function PhysicsComponentView({ properties, children, position, rotation, scale, editMode, nodeId, registerRigidBodyRef }) {
-    const { type, colliders } = properties, otherProps = __rest(properties, ["type", "colliders"]);
+    const { type, colliders, sensor } = properties, otherProps = __rest(properties, ["type", "colliders", "sensor"]);
     const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
     const rigidBodyRef = useRef(null);
     // Register RigidBody ref when it's available
@@ -95,12 +101,49 @@ function PhysicsComponentView({ properties, children, position, rotation, scale,
             }
         };
     }, [nodeId, registerRigidBodyRef]);
+    // Event handlers for physics interactions
+    const handleIntersectionEnter = useCallback((payload) => {
+        if (!nodeId)
+            return;
+        gameEvents.emit('sensor:enter', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+    const handleIntersectionExit = useCallback((payload) => {
+        if (!nodeId)
+            return;
+        gameEvents.emit('sensor:exit', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+    const handleCollisionEnter = useCallback((payload) => {
+        if (!nodeId)
+            return;
+        gameEvents.emit('collision:enter', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+    const handleCollisionExit = useCallback((payload) => {
+        if (!nodeId)
+            return;
+        gameEvents.emit('collision:exit', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
     // In edit mode, include position/rotation in key to force remount when transform changes
     // This ensures the RigidBody debug visualization updates even when physics is paused
     const rbKey = editMode
         ? `${type || 'dynamic'}_${colliderType}_${position === null || position === void 0 ? void 0 : position.join(',')}_${rotation === null || rotation === void 0 ? void 0 : rotation.join(',')}`
         : `${type || 'dynamic'}_${colliderType}`;
-    return (_jsx(RigidBody, Object.assign({ ref: rigidBodyRef, type: type, colliders: colliderType, position: position, rotation: rotation, scale: scale }, otherProps, { children: children }), rbKey));
+    return (_jsx(RigidBody, Object.assign({ ref: rigidBodyRef, type: type, colliders: colliderType, position: position, rotation: rotation, scale: scale, sensor: sensor, userData: { entityId: nodeId }, onIntersectionEnter: handleIntersectionEnter, onIntersectionExit: handleIntersectionExit, onCollisionEnter: handleCollisionEnter, onCollisionExit: handleCollisionExit }, otherProps, { children: children }), rbKey));
 }
 const PhysicsComponent = {
     name: 'Physics',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-three-game",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "description": "Batteries included React Three Fiber game engine",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/react-three-game-skill/react-three-game/SKILL.md

@@ -378,3 +378,77 @@ registerComponent(MyComponent);
 
 **Field types**: `vector3`, `number`, `string`, `color`, `boolean`, `select`, `custom`
 
+## Game Events
+
+A general-purpose event system for game-wide communication. Handles physics events, gameplay events, and any custom events.
+
+### Core API
+
+```tsx
+import { gameEvents, useGameEvent } from 'react-three-game';
+
+// Emit events
+gameEvents.emit('player:death', { playerId: 'p1', cause: 'lava' });
+gameEvents.emit('score:change', { delta: 100, total: 500 });
+
+// Subscribe (React hook - auto cleanup on unmount)
+useGameEvent('player:death', (payload) => {
+  showGameOver(payload.cause);
+}, []);
+
+// Subscribe (manual - returns unsubscribe function)
+const unsub = gameEvents.on('score:change', (payload) => {
+  updateUI(payload.total);
+});
+unsub(); // cleanup
+```
+
+### Built-in Physics Events
+
+Physics components automatically emit these events:
+
+| Event | When | Payload |
+|-------|------|---------|
+| `sensor:enter` | Something enters a sensor collider | `{ sourceEntityId, targetEntityId, targetRigidBody }` |
+| `sensor:exit` | Something exits a sensor collider | `{ sourceEntityId, targetEntityId, targetRigidBody }` |
+| `collision:enter` | A collision starts | `{ sourceEntityId, targetEntityId, targetRigidBody }` |
+| `collision:exit` | A collision ends | `{ sourceEntityId, targetEntityId, targetRigidBody }` |
+
+See [Advanced Physics](./rules/ADVANCED_PHYSICS.md) for sensor setup and collision handling patterns.
+
+### TypeScript: Typed Custom Events
+
+Extend `GameEventMap` for type-safe custom events:
+
+```typescript
+declare module 'react-three-game' {
+  interface GameEventMap {
+    'player:death': { playerId: string; cause: string };
+    'score:change': { delta: number; total: number };
+    'level:complete': { levelId: number; time: number };
+  }
+}
+```
+
+### Common Patterns
+
+```tsx
+// Gameplay controller
+function GameController() {
+  const [score, setScore] = useState(0);
+
+  useGameEvent('score:change', ({ total }) => setScore(total), []);
+  useGameEvent('player:death', () => setGameOver(true), []);
+
+  return <ScoreUI score={score} />;
+}
+
+// Pickup system
+useGameEvent('sensor:enter', (payload) => {
+  if (payload.sourceEntityId.startsWith('coin-')) {
+    gameEvents.emit('score:change', { delta: 10, total: score + 10 });
+    removeEntity(payload.sourceEntityId);
+  }
+}, [score]);
+```
+

package/react-three-game-skill/react-three-game/rules/ADVANCED_PHYSICS.md

@@ -49,7 +49,7 @@ Complete reference for `Physics` component properties:
 | `enabledTranslations` | `[bool, bool, bool]` | `[true, true, true]` | Lock per axis (X, Y, Z) |
 | `enabledRotations` | `[bool, bool, bool]` | `[true, true, true]` | Lock rotation per axis |
 | `ccd` | `boolean` | `false` | Continuous collision detection (fast objects) |
-| `sensor` | `boolean` | `false` | Trigger only, no collision response |
+| `sensor` | `boolean` | `false` | Trigger only, no collision response (see Sensors & Events) |
 | `collisionGroups` | `number` | - | Rapier collision groups bitfield |
 | `solverGroups` | `number` | - | Rapier solver groups bitfield |
 
@@ -347,3 +347,108 @@ Add multiple instances - they'll be automatically batched:
 - **Scale handling**: Visual scale is applied per-instance, but collider scale may differ
 - **Transform updates**: Use `updateNodeById` to move instances (triggers re-sync)
 - **Memory**: One set of GPU buffers shared across all instances
+
+## Sensors & Collision Events
+
+Sensors are colliders that detect intersections without generating physical contact forces. Use them for trigger zones, pickup areas, damage zones, and gameplay triggers.
+
+### Creating a Sensor
+
+Set `sensor: true` in the Physics component:
+
+```json
+{
+  "id": "trigger-zone",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [0, 1, 0] } },
+    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [4, 2, 4] } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed", "sensor": true } }
+  }
+}
+```
+
+### Physics Event Payload
+
+All physics events include:
+
+```typescript
+{
+  sourceEntityId: string;           // The prefab entity that owns the collider
+  targetEntityId: string | null;    // The other entity (if it's a prefab entity)
+  targetRigidBody: RapierRigidBody; // Direct access to the other RigidBody
+}
+```
+
+`targetEntityId` is `null` when colliding with non-prefab physics bodies (custom R3F components). Use `targetRigidBody` to inspect those.
+
+### Common Sensor Patterns
+
+**Pickup Item:**
+```json
+{
+  "id": "coin",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [5, 0.5, 0] } },
+    "model": { "type": "Model", "properties": { "filename": "models/coin.glb" } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed", "sensor": true } }
+  }
+}
+```
+
+```tsx
+useGameEvent('sensor:enter', (payload) => {
+  if (payload.sourceEntityId === 'coin' && payload.targetEntityId === 'player') {
+    removeCoin();
+    gameEvents.emit('score:change', { delta: 100, total: score + 100 });
+  }
+}, [score]);
+```
+
+**Damage Zone:**
+```json
+{
+  "id": "lava",
+  "components": {
+    "transform": { "type": "Transform", "properties": { "position": [0, 0, 0] } },
+    "geometry": { "type": "Geometry", "properties": { "geometryType": "box", "args": [10, 0.5, 10] } },
+    "material": { "type": "Material", "properties": { "color": "#ff4400" } },
+    "physics": { "type": "Physics", "properties": { "type": "fixed", "sensor": true } }
+  }
+}
+```
+
+```tsx
+useGameEvent('sensor:enter', ({ sourceEntityId, targetEntityId }) => {
+  if (sourceEntityId === 'lava') {
+    gameEvents.emit('player:damage', { entityId: targetEntityId, amount: 50 });
+  }
+}, []);
+```
+
+**Level Transition:**
+```tsx
+useGameEvent('sensor:enter', ({ sourceEntityId, targetEntityId }) => {
+  if (sourceEntityId === 'exit-door' && targetEntityId === 'player') {
+    loadNextLevel();
+  }
+}, []);
+```
+
+### Interop with Custom R3F Physics
+
+For custom RigidBody components to participate in the event system, set `userData.entityId`:
+
+```tsx
+<RigidBody userData={{ entityId: 'player' }}>
+  <PlayerMesh />
+</RigidBody>
+```
+
+Now when prefab sensors detect this body, `targetEntityId` will be `'player'`.
+
+### Tips
+
+- Sensors fire events for **all** intersecting bodies - filter by ID
+- `sensor:exit` fires when something leaves a sensor zone
+- `collision:enter/exit` fires for non-sensor physics bodies
+- Entity IDs stored in `RigidBody.userData.entityId`

package/src/index.ts

@@ -35,6 +35,13 @@ export type { Component } from './tools/prefabeditor/components/ComponentRegistr
 export type { FieldDefinition, FieldType } from './tools/prefabeditor/components/Input';
 export type { Prefab, GameObject, ComponentData } from './tools/prefabeditor/types';
 
+// Game Events (physics + custom events)
+export { gameEvents, useGameEvent, getEntityIdFromRigidBody } from './tools/prefabeditor/GameEvents';
+export type { GameEventType, GameEventMap, GameEventPayload, PhysicsEventType, PhysicsEventPayload } from './tools/prefabeditor/GameEvents';
+// Backward compatibility aliases
+export { entityEvents, useEntityEvent } from './tools/prefabeditor/GameEvents';
+export type { EntityEventType, EntityEventPayload } from './tools/prefabeditor/GameEvents';
+
 // Asset Tools
 export { DragDropLoader } from './tools/dragdrop/DragDropLoader';
 export {

package/src/tools/prefabeditor/GameEvents.ts

@@ -0,0 +1,191 @@
+import { useEffect, useCallback } from 'react';
+import type { RapierRigidBody } from '@react-three/rapier';
+
+// ============================================================================
+// Built-in Event Types & Payloads
+// ============================================================================
+
+/** Physics event types (built-in) */
+export type PhysicsEventType =
+    | 'sensor:enter'
+    | 'sensor:exit'
+    | 'collision:enter'
+    | 'collision:exit';
+
+/** Payload for physics events */
+export interface PhysicsEventPayload {
+    sourceEntityId: string;
+    targetEntityId: string | null;
+    targetRigidBody: RapierRigidBody | null | undefined;
+}
+
+// ============================================================================
+// Event Type Registry - Maps event names to their payload types
+// ============================================================================
+
+/**
+ * Register your custom event types here by extending this interface:
+ *
+ * declare module 'react-three-game' {
+ *   interface GameEventMap {
+ *     'player:death': { playerId: string; cause: string };
+ *     'score:change': { delta: number; total: number };
+ *   }
+ * }
+ */
+export interface GameEventMap {
+    'sensor:enter': PhysicsEventPayload;
+    'sensor:exit': PhysicsEventPayload;
+    'collision:enter': PhysicsEventPayload;
+    'collision:exit': PhysicsEventPayload;
+}
+
+/** All registered event types */
+export type GameEventType = keyof GameEventMap | (string & {});
+
+/** Get payload type for an event, or fallback to generic */
+export type GameEventPayload<T extends string> = T extends keyof GameEventMap
+    ? GameEventMap[T]
+    : Record<string, unknown>;
+
+// ============================================================================
+// Event System Implementation
+// ============================================================================
+
+type EventHandler<T = unknown> = (payload: T) => void;
+
+// Internal subscriber storage
+const subscribers = new Map<string, Set<EventHandler<any>>>();
+
+/**
+ * Game event system for all game interactions.
+ *
+ * Built-in physics events:
+ * - sensor:enter - Something entered a sensor collider
+ * - sensor:exit - Something exited a sensor collider
+ * - collision:enter - A collision started
+ * - collision:exit - A collision ended
+ *
+ * Custom events:
+ * - Emit any event type with any payload
+ * - Extend GameEventMap interface for type safety
+ *
+ * @example
+ * // Physics events (typed)
+ * gameEvents.emit('sensor:enter', { sourceEntityId: 'zone', targetEntityId: 'player', targetRigidBody: rb });
+ *
+ * // Custom events
+ * gameEvents.emit('player:death', { playerId: 'p1', cause: 'lava' });
+ * gameEvents.emit('level:complete', { levelId: 3, time: 45.2 });
+ */
+export const gameEvents = {
+    /**
+     * Emit an event to all subscribers
+     */
+    emit<T extends string>(type: T, payload: GameEventPayload<T>): void {
+        const handlers = subscribers.get(type);
+        if (handlers) {
+            handlers.forEach(handler => {
+                try {
+                    handler(payload);
+                } catch (e) {
+                    console.error(`Error in gameEvents handler for ${type}:`, e);
+                }
+            });
+        }
+    },
+
+    /**
+     * Subscribe to an event type
+     * @returns Unsubscribe function
+     */
+    on<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): () => void {
+        if (!subscribers.has(type)) {
+            subscribers.set(type, new Set());
+        }
+        subscribers.get(type)!.add(handler);
+
+        return () => {
+            subscribers.get(type)?.delete(handler);
+        };
+    },
+
+    /**
+     * Unsubscribe from an event type
+     */
+    off<T extends string>(type: T, handler: EventHandler<GameEventPayload<T>>): void {
+        subscribers.get(type)?.delete(handler);
+    },
+
+    /**
+     * Remove all subscribers (useful for cleanup/reset)
+     */
+    clear(): void {
+        subscribers.clear();
+    },
+
+    /**
+     * Check if an event type has any subscribers
+     */
+    hasListeners(type: string): boolean {
+        return (subscribers.get(type)?.size ?? 0) > 0;
+    }
+};
+
+/**
+ * React hook to subscribe to game events.
+ * Automatically cleans up on unmount.
+ *
+ * @example
+ * // Physics event
+ * useGameEvent('sensor:enter', (payload) => {
+ *   if (payload.sourceEntityId === 'coin') collectCoin();
+ * }, []);
+ *
+ * // Custom event
+ * useGameEvent('player:death', (payload) => {
+ *   showGameOver(payload.cause);
+ * }, []);
+ */
+export function useGameEvent<T extends string>(
+    type: T,
+    handler: EventHandler<GameEventPayload<T>>,
+    deps: unknown[] = []
+): void {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const stableHandler = useCallback(handler, deps);
+
+    useEffect(() => {
+        return gameEvents.on(type, stableHandler);
+    }, [type, stableHandler]);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Helper to extract entity ID from Rapier collision data.
+ * Entity IDs are stored in RigidBody userData.
+ */
+export function getEntityIdFromRigidBody(rigidBody: RapierRigidBody | null | undefined): string | null {
+    if (!rigidBody) return null;
+    const userData = rigidBody.userData as { entityId?: string } | undefined;
+    return userData?.entityId ?? null;
+}
+
+// ============================================================================
+// Backward Compatibility Aliases
+// ============================================================================
+
+/** @deprecated Use gameEvents instead */
+export const entityEvents = gameEvents;
+
+/** @deprecated Use useGameEvent instead */
+export const useEntityEvent = useGameEvent;
+
+/** @deprecated Use GameEventType instead */
+export type EntityEventType = PhysicsEventType;
+
+/** @deprecated Use PhysicsEventPayload instead */
+export type EntityEventPayload = PhysicsEventPayload;

package/src/tools/prefabeditor/components/PhysicsComponent.tsx

@@ -1,10 +1,11 @@
 import { RigidBody, RapierRigidBody } from "@react-three/rapier";
-import type { RigidBodyOptions } from "@react-three/rapier";
+import type { RigidBodyOptions, CollisionPayload, IntersectionEnterPayload, IntersectionExitPayload } from "@react-three/rapier";
 import type { ReactNode } from 'react';
-import { useRef, useEffect } from 'react';
+import { useRef, useEffect, useCallback } from 'react';
 import { Component } from "./ComponentRegistry";
 import { FieldRenderer, FieldDefinition } from "./Input";
 import { ComponentData } from "../types";
+import { gameEvents, getEntityIdFromRigidBody } from "../GameEvents";
 
 export type PhysicsProps = RigidBodyOptions;
 
@@ -71,6 +72,11 @@ const physicsFields: FieldDefinition[] = [
         label: 'Gravity Scale',
         step: 0.1,
     },
+    {
+        name: 'sensor',
+        type: 'boolean',
+        label: 'Sensor (Trigger Only)',
+    },
 ];
 
 function PhysicsComponentEditor({ component, onUpdate }: { component: ComponentData; onUpdate: (newComp: any) => void }) {
@@ -95,7 +101,7 @@ interface PhysicsViewProps {
 }
 
 function PhysicsComponentView({ properties, children, position, rotation, scale, editMode, nodeId, registerRigidBodyRef }: PhysicsViewProps) {
-    const { type, colliders, ...otherProps } = properties;
+    const { type, colliders, sensor, ...otherProps } = properties;
     const colliderType = colliders || (type === 'fixed' ? 'trimesh' : 'hull');
     const rigidBodyRef = useRef<RapierRigidBody>(null);
 
@@ -111,6 +117,43 @@ function PhysicsComponentView({ properties, children, position, rotation, scale,
         };
     }, [nodeId, registerRigidBodyRef]);
 
+    // Event handlers for physics interactions
+    const handleIntersectionEnter = useCallback((payload: IntersectionEnterPayload) => {
+        if (!nodeId) return;
+        gameEvents.emit('sensor:enter', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+
+    const handleIntersectionExit = useCallback((payload: IntersectionExitPayload) => {
+        if (!nodeId) return;
+        gameEvents.emit('sensor:exit', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+
+    const handleCollisionEnter = useCallback((payload: CollisionPayload) => {
+        if (!nodeId) return;
+        gameEvents.emit('collision:enter', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+
+    const handleCollisionExit = useCallback((payload: CollisionPayload) => {
+        if (!nodeId) return;
+        gameEvents.emit('collision:exit', {
+            sourceEntityId: nodeId,
+            targetEntityId: getEntityIdFromRigidBody(payload.other.rigidBody),
+            targetRigidBody: payload.other.rigidBody,
+        });
+    }, [nodeId]);
+
     // In edit mode, include position/rotation in key to force remount when transform changes
     // This ensures the RigidBody debug visualization updates even when physics is paused
     const rbKey = editMode
@@ -126,6 +169,12 @@ function PhysicsComponentView({ properties, children, position, rotation, scale,
             position={position}
             rotation={rotation}
             scale={scale}
+            sensor={sensor}
+            userData={{ entityId: nodeId }}
+            onIntersectionEnter={handleIntersectionEnter}
+            onIntersectionExit={handleIntersectionExit}
+            onCollisionEnter={handleCollisionEnter}
+            onCollisionExit={handleCollisionExit}
             {...otherProps}
         >
             {children}