@combos-fun/plugin-renderer-3d-event 0.1.15 → 0.1.16

package/agent-skill.md

@@ -1,80 +1,29 @@
 # `@combos-fun/plugin-renderer-3d-event` — Agent notes
 
-Pointer/touch picking for the 3D pipeline. Canvas pointer events are raycast through the active Three camera and emitted by `Event3D`.
-
-Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, hierarchy, and object tagging. Use `Event3D`, not the 2D `Event`.
-
-## Public API
+Pointer raycast. No keyboard. Parent: `plugin-renderer-3d`. Use `Event3D`, not 2D `Event`.
 
 ```ts
-import {
-  Event3D,
-  Event3DSystem,
-  type Event3DParams,
-  type Event3DParam,
-  type Event3DHitArea,
-  type Event3DHitAreaType,
-  type Event3DSystemParams,
-} from '@combos-fun/plugin-renderer-3d-event';
+import { Event3D, Event3DSystem } from '@combos-fun/plugin-renderer-3d-event';
 ```
 
-`componentName = 'Event3D'`; `systemName = 'Event3DSystem'`; `Event3DSystemParams` is empty. This package has no keyboard API.
-
-## Hit area
-
-`Event3DParams` contains optional `hitArea`. Without one, officially tagged visual meshes are pickable. An invisible hit area also makes an empty GameObject pickable:
+`componentName = 'Event3D'`. `systemName = 'Event3DSystem'`.
 
-| Type | Fields and defaults |
-|------|---------------------|
-| `box` | `width: 1`, `height: 1`, `depth: 1` |
-| `sphere` | `radius: 0.5` |
-| `plane` | `width: 1`, `height: 1` |
+`hitArea` is optional. Without it, tagged visual meshes are pickable. An invisible hit area makes an empty GameObject pickable.
 
-Unknown hit-area types create no mesh. Changing `hitArea` disposes the previous geometry/material and creates a replacement.
+| Type | Defaults |
+| --- | --- |
+| `box` | `width` / `height` / `depth` = `1` |
+| `sphere` | `radius` = `0.5` |
+| `plane` | `width` / `height` = `1` |
 
-## Events and payload
-
-Emitted names: `touchstart`, `touchmove`, `touchend`, `tap`, `touchendoutside`, `touchcancel`.
+Events: `touchstart`, `touchmove`, `touchend`, `tap`, `touchendoutside`, `touchcancel`.
 
 ```ts
-event3D.on('tap', (payload) => {
-  payload.stopPropagation();
-  payload.data.pointerId;       // browser pointer id
-  payload.data.position;        // { x, y }, canvas-local CSS pixels
-  payload.data.localPosition;   // { x, y, z }, intersected object's local space
-  payload.gameObject;           // resolved tagged GameObject
+event3D.on('tap', ({ stopPropagation, data, gameObject }) => {
+  data.pointerId;
+  data.position;      // { x, y } canvas CSS pixels
+  data.localPosition; // { x, y, z }
 });
 ```
 
-## Runtime and lifecycle
-
-- The nearest ray intersection that resolves to a GameObject with `Event3D` wins; intersections without `Event3D` are skipped.
-- `touchstart` records the pressed target. `touchmove` emits only on the object currently under the pointer.
-- Releasing on the original target emits `touchend` then `tap`.
-- Releasing elsewhere emits `touchendoutside` on the pressed target; if another target is under the pointer, it also receives `touchend`.
-- Pointer cancel/leave emits `touchcancel` on the pressed target.
-- `stopPropagation()` forwards to the underlying browser event's `stopPropagation`.
-- Removing `Event3D` removes its hit area, listeners, and pending pointer records. System destruction removes canvas listeners and all hit areas.
-
-## Package-specific pitfalls
-
-- Custom Three objects must be tagged through `attachVisual` or `tagObject3D`.
-- A transparent hit area remains raycastable and can be the nearest hit.
-- Pixi hit areas and 2D `EventSystem` do not participate in this raycast.
-
-## Minimal example
-
-```ts
-const box = new GameObject('box');
-box.addComponent(new Graphics3D({ shape: 'box', color: 0xffaa00 }));
-box.addComponent(new Event3D({
-  hitArea: { type: 'box', width: 1, height: 1, depth: 1 },
-}));
-box.getComponent(Event3D)!.on('tap', ({ gameObject }) => {
-  // handle gameObject
-});
-```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-3d-event run build`
+Nearest hit that has `Event3D` wins. `touchmove` emits only while the pointer is over an `Event3D`. Release on the pressed target emits `touchend` then `tap`. Release elsewhere emits `touchendoutside` on the pressed target, and `touchend` on a different target under the pointer. Cancel or leave emits `touchcancel`. Unknown hit-area types create no mesh. `stopPropagation()` forwards to the browser event. Custom meshes must be tagged with `attachVisual` or `tagObject3D`. A transparent hit area still wins the raycast. 2D `Event` does not participate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-event",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Pointer / touch event input via Three.js raycasting",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-event.esm.js",
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "three": "^0.172.0",
-    "@combos-fun/plugin-renderer-3d": "0.1.15",
-    "@combos-fun/engine": "0.1.15"
+    "@combos-fun/engine": "0.1.16",
+    "@combos-fun/plugin-renderer-3d": "0.1.16"
   },
   "keywords": [
     "combos-fun",