@gwenjs/camera-core 0.1.0

package/README.md

@@ -0,0 +1,188 @@
+# `@gwenjs/camera-core`
+
+ECS camera system for Gwen. Provides the components, `CameraSystem` orchestrator, and `CameraCorePlugin` shared by `@gwenjs/camera2d` and `@gwenjs/camera3d`.
+
+> **Note** — you normally do not install this package directly. Use `@gwenjs/camera2d` or `@gwenjs/camera3d` instead. They install `CameraCorePlugin` automatically.
+
+## Installation
+
+```sh
+npm install @gwenjs/camera-core
+```
+
+## Quick start
+
+Since `camera-core` is a low-level primitive, the canonical way to use it is via a
+`gwen.config.ts` with `CameraCorePlugin` and a setup system:
+
+```ts
+// gwen.config.ts
+import { defineConfig } from "@gwenjs/app";
+import { defineSystem, onUpdate } from "@gwenjs/core/system";
+import { useEngine } from "@gwenjs/core";
+import { useViewportManager } from "@gwenjs/renderer-core";
+import { CameraCorePlugin, Camera, cameraViewportMap } from "@gwenjs/camera-core";
+
+const CameraSetupSystem = defineSystem("CameraSetupSystem", () => {
+  const engine = useEngine();
+  const viewports = useViewportManager();
+
+  // Register a full-screen viewport (normalized [0–1])
+  viewports.set("main", { x: 0, y: 0, width: 1, height: 1 });
+
+  // Create the camera entity
+  const camId = engine.createEntity();
+  engine.addComponent(camId, Camera, {
+    active: 1,
+    priority: 0,
+    projectionType: 0, // 0 = orthographic, 1 = perspective
+    x: 0,
+    y: 0,
+    z: 0,
+    rotX: 0,
+    rotY: 0,
+    rotZ: 0,
+    zoom: 1,
+    fov: Math.PI / 3,
+    near: -1000,
+    far: 1000,
+  });
+  cameraViewportMap.set(camId, "main");
+});
+
+export default defineConfig({
+  plugins: [CameraCorePlugin(), CameraSetupSystem],
+});
+```
+
+## ECS components
+
+| Component      | Purpose                                                                                 |
+| -------------- | --------------------------------------------------------------------------------------- |
+| `Camera`       | Core camera state — position, rotation, projection, active flag, priority               |
+| `FollowTarget` | Lerps the camera toward another entity's position each frame                            |
+| `CameraBounds` | Clamps the camera position to a bounding box after movement                             |
+| `CameraShake`  | Trauma-based screen shake — offsets the rendered position without moving `Camera.x/y/z` |
+| `CameraPath`   | ECS bookmark for path-following state (index + progress in current segment)             |
+
+### `Camera` fields
+
+```ts
+{
+  active: 0 | 1,       // 0 = inactive, 1 = active
+  priority: number,    // higher priority wins the viewport slot
+  projectionType: 0 | 1, // 0 = orthographic, 1 = perspective
+  x, y, z: number,    // world position
+  rotX, rotY, rotZ: number, // euler rotation (radians)
+  zoom: number,        // orthographic zoom
+  fov: number,         // perspective field-of-view (radians)
+  near, far: number,   // clipping planes
+}
+```
+
+### `FollowTarget` fields
+
+```ts
+{
+  entityId: number,    // target entity (u32 cast of EntityId)
+  lerp: number,        // interpolation factor per frame [0–1]
+  offsetX, offsetY, offsetZ: number,
+}
+```
+
+### `CameraBounds` fields
+
+```ts
+{ minX, minY, minZ, maxX, maxY, maxZ: number }
+```
+
+### `CameraShake` fields
+
+```ts
+{
+  trauma: number,  // current trauma [0–1], add to it to trigger shake
+  decay: number,   // trauma lost per second
+  maxX: number,    // max horizontal offset in world units
+  maxY: number,    // max vertical offset in world units
+}
+```
+
+## Side-car stores
+
+`cameraViewportMap` and `cameraPathStore` are module-level `Map`s that live alongside the ECS components because strings and complex objects cannot be stored in SoA buffers.
+
+```ts
+import { cameraViewportMap, cameraPathStore } from "@gwenjs/camera-core";
+import type { CameraPathData } from "@gwenjs/camera-core";
+
+// Assign a camera to a viewport
+cameraViewportMap.set(camId, "main");
+
+// Start a path
+const pathData: CameraPathData = {
+  waypoints: [
+    { position: { x: 200, y: 0, z: 0 }, duration: 1.5, easing: "easeInOut" },
+    { position: { x: 200, y: 300, z: 0 }, duration: 1.0 },
+  ],
+  opts: { loop: false, onComplete: () => console.log("done") },
+  elapsed: 0,
+};
+engine.addComponent(camId, CameraPath, { index: 0, progress: 0 });
+cameraPathStore.set(camId, pathData);
+```
+
+## Engine hooks
+
+`CameraSystem` emits these hooks each frame via `engine.hooks`:
+
+| Hook                | Payload                                                | When                                                 |
+| ------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
+| `camera:activate`   | `{ viewportId: string, entityId: EntityId }`           | First time a camera becomes active on a viewport     |
+| `camera:deactivate` | `{ viewportId: string }`                               | The active camera is deactivated with no replacement |
+| `camera:switch`     | `{ viewportId: string, from: EntityId, to: EntityId }` | Active camera changes from one entity to another     |
+
+```ts
+engine.hooks.hook("camera:activate", ({ viewportId, entityId }) => {
+  console.log(`camera ${entityId} is now active on ${viewportId}`);
+});
+```
+
+`viewport:*` hooks (`viewport:add`, `viewport:resize`, `viewport:remove`) are declared in `@gwenjs/renderer-core`.
+
+## `CameraSystem` pipeline (per frame)
+
+1. `CameraManager.clearFrame()` — stale states are discarded
+2. For each entity in `useQuery([Camera])` with `active = 1`:
+   - Apply `FollowTarget` lerp toward the target entity — **or** advance `CameraPath` waypoints
+   - Clamp to `CameraBounds`
+   - Compute `CameraShake` offset (does **not** modify `Camera.x/y/z`)
+   - Push `CameraState` to `CameraManager`
+3. Detect semantic changes per viewport and emit `camera:activate / deactivate / switch`
+
+## Multi-camera / priority
+
+Multiple cameras can target the same viewport. The one with the highest `Camera.priority` wins. On equal priority, the last entity to push its state wins.
+
+## Building a custom camera handle
+
+If `camera2d`/`camera3d` don't fit your needs, you can build your own on top of `camera-core`:
+
+```ts
+import { CameraCorePlugin, Camera, cameraViewportMap } from "@gwenjs/camera-core";
+import { useCameraManager } from "@gwenjs/renderer-core";
+import { defineSystem, onUpdate } from "@gwenjs/core/system";
+
+await engine.use(CameraCorePlugin());
+
+// Your system reads CameraManager after CameraSystem runs
+const MyRenderSystem = defineSystem("MyRenderSystem", () => {
+  const cameras = useCameraManager();
+  onUpdate(() => {
+    const state = cameras.get("main");
+    if (state) {
+      const { x, y, z } = state.worldTransform.position;
+      // apply to your renderer
+    }
+  });
+});
+```

package/dist/camera-core-plugin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file CameraCorePlugin — installs CameraManager, ViewportManager, and CameraSystem.
+ *
+ * Called automatically by Camera2DPlugin and Camera3DPlugin.
+ * Users do not install this plugin manually unless they are building a custom
+ * camera composable from scratch.
+ *
+ * @example
+ * ```ts
+ * // Only if building a custom camera — normally not needed
+ * await engine.use(CameraCorePlugin())
+ * ```
+ */
+export declare const CameraCorePlugin: (options?: unknown) => {
+    name: string;
+    setup(engine: import('@gwenjs/core').GwenEngine): Promise<void>;
+};
+//# sourceMappingURL=camera-core-plugin.d.ts.map

package/dist/camera-core-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-core-plugin.d.ts","sourceRoot":"","sources":["../src/camera-core-plugin.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAMH,eAAO,MAAM,gBAAgB;;;CAO1B,CAAC"}

package/dist/camera-path-store.d.ts

@@ -0,0 +1,4 @@
+import { EntityId } from '@gwenjs/core';
+import { CameraPathData } from './types.js';
+export declare const cameraPathStore: Map<EntityId, CameraPathData>;
+//# sourceMappingURL=camera-path-store.d.ts.map

package/dist/camera-path-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-path-store.d.ts","sourceRoot":"","sources":["../src/camera-path-store.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,eAAe,+BAAsC,CAAC"}

package/dist/camera-system.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file CameraSystem — single orchestrator for all camera entities.
+ *
+ * Pipeline per frame (onAfterUpdate):
+ *   1. clearFrame() on CameraManager so stale states don't persist
+ *   2. For each active camera entity:
+ *      a. Apply FollowTarget (lerp toward target)  — or —
+ *         Advance CameraPath (interpolate waypoints)
+ *      b. Clamp to CameraBounds
+ *      c. Apply CameraShake offset (does NOT write Camera.x/y/z)
+ *      d. Push CameraState to CameraManager
+ *   3. Detect semantic changes per viewport and emit camera:* hooks
+ */
+export declare const CameraSystem: import('@gwenjs/core').GwenPlugin;
+//# sourceMappingURL=camera-system.d.ts.map

package/dist/camera-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-system.d.ts","sourceRoot":"","sources":["../src/camera-system.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAgBH,eAAO,MAAM,YAAY,mCA+LvB,CAAC"}

package/dist/camera-viewport-map.d.ts

@@ -0,0 +1,3 @@
+import { EntityId } from '@gwenjs/core';
+export declare const cameraViewportMap: Map<EntityId, string>;
+//# sourceMappingURL=camera-viewport-map.d.ts.map

package/dist/camera-viewport-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera-viewport-map.d.ts","sourceRoot":"","sources":["../src/camera-viewport-map.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,uBAA8B,CAAC"}

package/dist/components.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @file ECS component definitions for the camera system.
+ *
+ * All SoA arrays are indexed by EntityId.
+ * String data (viewportId) and object data (CameraPathData) live in separate
+ * Maps — see camera-viewport-map.ts and camera-path-store.ts.
+ */
+/**
+ * Core camera component. One per camera entity.
+ *
+ * projectionType: 0 = orthographic, 1 = perspective
+ * active: 0 = inactive, 1 = active
+ *
+ * The `viewportId` string is stored in `cameraViewportMap` (camera-viewport-map.ts),
+ * not here — strings cannot live in SoA buffers.
+ */
+export declare const Camera: import('@gwenjs/core').ComponentDefinition<{
+    active: {
+        type: "u32";
+        byteLength: number;
+        read: "getUint32";
+        write: "setUint32";
+    };
+    priority: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    x: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    y: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    z: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    rotX: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    rotY: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    rotZ: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    projectionType: {
+        type: "u32";
+        byteLength: number;
+        read: "getUint32";
+        write: "setUint32";
+    };
+    zoom: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    fov: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    near: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    far: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+}>;
+/**
+ * Follow-target behaviour. When present on a camera entity, `CameraSystem`
+ * lerps the camera position toward the target entity's Camera x/y/z each frame.
+ *
+ * Mutually exclusive with `CameraPath` — adding FollowTarget removes CameraPath and vice versa.
+ */
+export declare const FollowTarget: import('@gwenjs/core').ComponentDefinition<{
+    entityId: {
+        type: "u64";
+        byteLength: number;
+        read: "getBigUint64";
+        write: "setBigUint64";
+    };
+    lerp: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    offsetX: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    offsetY: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    offsetZ: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+}>;
+/**
+ * Spatial clamp. `CameraSystem` clamps `Camera.x/y/z` to [min, max] after
+ * applying follow/path each frame.
+ */
+export declare const CameraBounds: import('@gwenjs/core').ComponentDefinition<{
+    minX: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    minY: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    minZ: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    maxX: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    maxY: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    maxZ: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+}>;
+/**
+ * Trauma-based screen shake.
+ *
+ * - `trauma` accumulates (clamped to [0,1]) and decays by `decay` per second.
+ * - `CameraSystem` computes a shake offset each frame proportional to trauma²
+ *   and adds it to the final `CameraState.worldTransform` **without** modifying
+ *   `Camera.x/y/z` — so the underlying position remains stable.
+ */
+export declare const CameraShake: import('@gwenjs/core').ComponentDefinition<{
+    trauma: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    decay: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    maxX: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+    maxY: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+}>;
+/**
+ * Path-following behaviour. The actual waypoints and options are stored in
+ * `cameraPathStore` (camera-path-store.ts). This component tracks position
+ * in the path.
+ *
+ * Mutually exclusive with `FollowTarget`.
+ */
+export declare const CameraPath: import('@gwenjs/core').ComponentDefinition<{
+    index: {
+        type: "u32";
+        byteLength: number;
+        read: "getUint32";
+        write: "setUint32";
+    };
+    progress: {
+        type: "f32";
+        byteLength: number;
+        read: "getFloat32";
+        write: "setFloat32";
+    };
+}>;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBjB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASvB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUvB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;EAQtB,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;EAMrB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file Camera error codes and error classes.
+ *
+ * All errors carry a `code`, a human-readable `hint`, and a `docsUrl`.
+ * Callers may log these errors before throwing or handling them.
+ */
+export declare const CameraErrorCodes: {
+    readonly VIEWPORT_NOT_FOUND: "CAMERA:VIEWPORT_NOT_FOUND";
+    readonly EMPTY_PATH: "CAMERA:EMPTY_PATH";
+    readonly PERSPECTIVE_FALLBACK: "CAMERA:PERSPECTIVE_FALLBACK";
+    readonly PRIORITY_CONFLICT: "CAMERA:PRIORITY_CONFLICT";
+};
+export type CameraErrorCode = (typeof CameraErrorCodes)[keyof typeof CameraErrorCodes];
+/**
+ * Thrown by `use2DCamera()`, `use3DCamera()`, and `Camera*Handle.setViewport()`
+ * when the requested viewport id is not registered in `ViewportManager`.
+ *
+ * @example
+ * ```ts
+ * const err = new CameraViewportNotFoundError('minimap')
+ * log.error(`[${err.code}] ${err.message} — ${err.hint}`)
+ * throw err
+ * ```
+ */
+export declare class CameraViewportNotFoundError extends Error {
+    readonly code: "CAMERA:VIEWPORT_NOT_FOUND";
+    readonly hint: string;
+    readonly docsUrl: string;
+    constructor(viewportId: string);
+}
+/**
+ * Thrown by `Camera*Handle.playPath()` when the waypoints array is empty.
+ *
+ * @example
+ * ```ts
+ * const err = new CameraEmptyPathError()
+ * log.error(`[${err.code}] ${err.message} — ${err.hint}`)
+ * throw err
+ * ```
+ */
+export declare class CameraEmptyPathError extends Error {
+    readonly code: "CAMERA:EMPTY_PATH";
+    readonly hint: string;
+    readonly docsUrl: string;
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEvF;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,8BAAuC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,UAAU,EAAE,MAAM;CAQ/B;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,sBAA+B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;;CAQ1B"}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { EntityId } from '@gwenjs/core';
+/**
+ * @file Public API for `@gwenjs/camera-core`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   Camera,
+ *   FollowTarget,
+ *   CameraShake,
+ *   CameraCorePlugin,
+ *   CameraErrorCodes,
+ *   cameraViewportMap,
+ *   cameraPathStore,
+ * } from '@gwenjs/camera-core'
+ * ```
+ */
+export { CameraErrorCodes, type CameraErrorCode, CameraViewportNotFoundError, CameraEmptyPathError, } from './errors.js';
+export type { EasingName, CameraWaypoint, PathOpts, CameraPathData, BlendOpts, FollowOpts, ShakeOpts, ShakeHandle, } from './types.js';
+export { Camera, FollowTarget, CameraBounds, CameraShake, CameraPath } from './components.js';
+export { cameraViewportMap } from './camera-viewport-map.js';
+export { cameraPathStore } from './camera-path-store.js';
+export { CameraSystem } from './camera-system.js';
+export { CameraCorePlugin } from './camera-core-plugin.js';
+declare module "@gwenjs/core" {
+    interface GwenRuntimeHooks {
+        /**
+         * Fired the first time a camera becomes active on a viewport.
+         * Not fired again until the camera is deactivated and a new one activates.
+         */
+        "camera:activate": (payload: {
+            viewportId: string;
+            entityId: EntityId;
+        }) => void;
+        /**
+         * Fired when the previously active camera on a viewport loses its active state
+         * and no replacement camera is found for that frame.
+         */
+        "camera:deactivate": (payload: {
+            viewportId: string;
+        }) => void;
+        /**
+         * Fired when the active camera on a viewport changes from one entity to another.
+         * Not fired on initial activation — use `camera:activate` for that.
+         */
+        "camera:switch": (payload: {
+            viewportId: string;
+            from: EntityId;
+            to: EntityId;
+        }) => void;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,UAAU,EACV,cAAc,EACd,QAAQ,EACR,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAI3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,gBAAgB;QACxB;;;WAGG;QACH,iBAAiB,EAAE,CAAC,OAAO,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,QAAQ,CAAA;SAAE,KAAK,IAAI,CAAC;QACjF;;;WAGG;QACH,mBAAmB,EAAE,CAAC,OAAO,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI,CAAC;QAC/D;;;WAGG;QACH,eAAe,EAAE,CAAC,OAAO,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,QAAQ,CAAC;YAAC,EAAE,EAAE,QAAQ,CAAA;SAAE,KAAK,IAAI,CAAC;KAC1F;CACF"}

package/dist/index.js

@@ -0,0 +1,353 @@
+import { Types as e, defineComponent as t, useEngine as n } from "@gwenjs/core";
+import { getOrCreateCameraManager as r, getOrCreateViewportManager as i, useCameraManager as a, useViewportManager as o } from "@gwenjs/renderer-core";
+//#region src/errors.ts
+var s = {
+	VIEWPORT_NOT_FOUND: "CAMERA:VIEWPORT_NOT_FOUND",
+	EMPTY_PATH: "CAMERA:EMPTY_PATH",
+	PERSPECTIVE_FALLBACK: "CAMERA:PERSPECTIVE_FALLBACK",
+	PRIORITY_CONFLICT: "CAMERA:PRIORITY_CONFLICT"
+}, c = class extends Error {
+	code = s.VIEWPORT_NOT_FOUND;
+	hint;
+	docsUrl;
+	constructor(e) {
+		super(`[GwenCamera] Viewport "${e}" not found.`), this.name = "CameraViewportNotFoundError", this.hint = `Declare it in defineConfig({ viewports: { "${e}": { x, y, width, height } } }) or call useViewportManager().set("${e}", region) at runtime.`, this.docsUrl = "https://gwenengine.dev/docs/camera#viewports";
+	}
+}, l = class extends Error {
+	code = s.EMPTY_PATH;
+	hint;
+	docsUrl;
+	constructor() {
+		super("[GwenCamera] playPath() requires at least one waypoint."), this.name = "CameraEmptyPathError", this.hint = "Provide a non-empty waypoints array to playPath().", this.docsUrl = "https://gwenengine.dev/docs/camera#playPath";
+	}
+}, u = t({
+	name: "Camera",
+	schema: {
+		active: e.u32,
+		priority: e.f32,
+		x: e.f32,
+		y: e.f32,
+		z: e.f32,
+		rotX: e.f32,
+		rotY: e.f32,
+		rotZ: e.f32,
+		projectionType: e.u32,
+		zoom: e.f32,
+		fov: e.f32,
+		near: e.f32,
+		far: e.f32
+	}
+}), d = t({
+	name: "FollowTarget",
+	schema: {
+		entityId: e.u64,
+		lerp: e.f32,
+		offsetX: e.f32,
+		offsetY: e.f32,
+		offsetZ: e.f32
+	}
+}), f = t({
+	name: "CameraBounds",
+	schema: {
+		minX: e.f32,
+		minY: e.f32,
+		minZ: e.f32,
+		maxX: e.f32,
+		maxY: e.f32,
+		maxZ: e.f32
+	}
+}), p = t({
+	name: "CameraShake",
+	schema: {
+		trauma: e.f32,
+		decay: e.f32,
+		maxX: e.f32,
+		maxY: e.f32
+	}
+}), m = t({
+	name: "CameraPath",
+	schema: {
+		index: e.u32,
+		progress: e.f32
+	}
+}), h = /* @__PURE__ */ new Map(), g = /* @__PURE__ */ new Map();
+//#endregion
+//#region ../../node_modules/.pnpm/unctx@2.5.0/node_modules/unctx/dist/index.mjs
+function _(e = {}) {
+	let t, n = !1, r = (e) => {
+		if (t && t !== e) throw Error("Context conflict");
+	}, i;
+	if (e.asyncContext) {
+		let t = e.AsyncLocalStorage || globalThis.AsyncLocalStorage;
+		t ? i = new t() : console.warn("[unctx] `AsyncLocalStorage` is not provided.");
+	}
+	let a = () => {
+		if (i) {
+			let e = i.getStore();
+			if (e !== void 0) return e;
+		}
+		return t;
+	};
+	return {
+		use: () => {
+			let e = a();
+			if (e === void 0) throw Error("Context is not available");
+			return e;
+		},
+		tryUse: () => a(),
+		set: (e, i) => {
+			i || r(e), t = e, n = !0;
+		},
+		unset: () => {
+			t = void 0, n = !1;
+		},
+		call: (e, a) => {
+			r(e), t = e;
+			try {
+				return i ? i.run(e, a) : a();
+			} finally {
+				n || (t = void 0);
+			}
+		},
+		async callAsync(e, r) {
+			t = e;
+			let a = () => {
+				t = e;
+			}, o = () => t === e ? a : void 0;
+			S.add(o);
+			try {
+				let a = i ? i.run(e, r) : r();
+				return n || (t = void 0), await a;
+			} finally {
+				S.delete(o);
+			}
+		}
+	};
+}
+function v(e = {}) {
+	let t = {};
+	return { get(n, r = {}) {
+		return t[n] || (t[n] = _({
+			...e,
+			...r
+		})), t[n];
+	} };
+}
+var y = typeof globalThis < "u" ? globalThis : typeof self < "u" ? self : typeof global < "u" ? global : typeof window < "u" ? window : {}, b = "__unctx__";
+y[b] || (y[b] = v());
+var x = "__unctx_async_handlers__", S = y[x] || (y[x] = /* @__PURE__ */ new Set()), C = _({ asyncContext: !1 }), w = class extends Error {
+	constructor(e) {
+		super(e), this.name = "GwenContextError";
+	}
+};
+function T() {
+	let e = C.tryUse();
+	if (!e) throw new w("[GWEN] useEngine() was called outside of an engine context.\nMake sure you are calling it inside defineSystem(), engine.run(), or a plugin lifecycle hook (setup, onUpdate, onRender, etc.).");
+	return e;
+}
+//#endregion
+//#region ../core/src/system.ts
+var E = null;
+function D() {
+	if (!E) throw Error("[GWEN] onUpdate/onRender/onBeforeUpdate/onAfterUpdate must be called inside a defineSystem() setup callback, not inside the lifecycle function itself.");
+	return E;
+}
+function O(e, t) {
+	let n = E;
+	E = e;
+	try {
+		t();
+	} finally {
+		E = n;
+	}
+}
+function k(e) {
+	D().onAfterUpdate(e);
+}
+function A(e, t) {
+	let n = typeof e == "string" ? e : e.name || "", r = typeof e == "function" ? e : t, i = [], a = [], o = [], s = [];
+	return {
+		name: n || (console.warn("[GWEN] defineSystem() called without a name. Pass a name as first argument: defineSystem('mySystem', () => { ... })"), "anonymous-system"),
+		setup(e) {
+			O({
+				onBeforeUpdate: (e) => i.push(e),
+				onUpdate: (e) => a.push(e),
+				onAfterUpdate: (e) => o.push(e),
+				onRender: (e) => s.push(e)
+			}, r);
+		},
+		onBeforeUpdate(e) {
+			for (let t = 0; t < i.length; t++) i[t](e);
+		},
+		onUpdate(e) {
+			for (let t = 0; t < a.length; t++) a[t](e);
+		},
+		onAfterUpdate(e) {
+			for (let t = 0; t < o.length; t++) o[t](e);
+		},
+		onRender() {
+			for (let e = 0; e < s.length; e++) s[e]();
+		}
+	};
+}
+function j(e) {
+	return T().createLiveQuery(e);
+}
+//#endregion
+//#region src/camera-system.ts
+function M(e, t) {
+	return Math.sin(t * 127.1 + e * 311.7) * e * e;
+}
+var N = A("CameraSystem", () => {
+	let e = n(), t = a();
+	o();
+	let r = j([u]), i = /* @__PURE__ */ new Map(), s = 0;
+	k((n) => {
+		s++;
+		let a = n / 1e3;
+		t.clearFrame();
+		for (let n of r) {
+			let r = n.id, i = e.getComponent(r, u);
+			if (!i || i.active !== 1) continue;
+			let o = h.get(r);
+			if (!o) continue;
+			let c = i.x, l = i.y, _ = i.z, v = e.hasComponent(r, d), y = g.has(r) && e.hasComponent(r, m);
+			if (v) {
+				let t = e.getComponent(r, d), n = t.entityId, a = e.getComponent(n, u);
+				if (a) {
+					let n = a.x + t.offsetX, o = a.y + t.offsetY, s = a.z + t.offsetZ;
+					c += (n - c) * t.lerp, l += (o - l) * t.lerp, _ += (s - _) * t.lerp, e.addComponent(r, u, {
+						...i,
+						x: c,
+						y: l,
+						z: _
+					});
+				}
+			} else if (y) {
+				let t = g.get(r), n = e.getComponent(r, m);
+				if (!n) continue;
+				let o = t.waypoints[n.index];
+				if (o) {
+					t.elapsed += a;
+					let s = Math.min(t.elapsed / o.duration, 1);
+					if (e.addComponent(r, m, {
+						...n,
+						progress: s
+					}), s >= 1) {
+						c = o.position.x, l = o.position.y, _ = o.position.z, e.addComponent(r, u, {
+							...i,
+							x: c,
+							y: l,
+							z: _
+						});
+						let a = n.index + 1;
+						a < t.waypoints.length ? (e.addComponent(r, m, {
+							...n,
+							index: a,
+							progress: 0
+						}), t.elapsed = 0) : t.opts.loop ? (e.addComponent(r, m, {
+							...n,
+							index: 0,
+							progress: 0
+						}), t.elapsed = 0, t.opts.onWaypoint?.(a - 1)) : (t.opts.onComplete?.(), g.delete(r), e.removeComponent(r, m));
+					} else {
+						let a = t.waypoints[n.index - 1], d = a ? a.position.x : i.x, f = a ? a.position.y : i.y, p = a ? a.position.z : i.z;
+						c = d + (o.position.x - d) * s, l = f + (o.position.y - f) * s, _ = p + (o.position.z - p) * s, e.addComponent(r, u, {
+							...i,
+							x: c,
+							y: l,
+							z: _
+						});
+					}
+				}
+			}
+			if (e.hasComponent(r, f)) {
+				let t = e.getComponent(r, f);
+				c = Math.max(t.minX, Math.min(t.maxX, c)), l = Math.max(t.minY, Math.min(t.maxY, l)), _ = Math.max(t.minZ, Math.min(t.maxZ, _)), e.addComponent(r, u, {
+					...i,
+					x: c,
+					y: l,
+					z: _
+				});
+			}
+			let b = 0, x = 0, S = e.getComponent(r, p);
+			if (S && S.trauma > 0) {
+				b = M(S.trauma, s) * S.maxX, x = M(S.trauma, s + 100) * S.maxY;
+				let t = Math.max(0, S.trauma - S.decay * a);
+				e.addComponent(r, p, {
+					...S,
+					trauma: t
+				});
+			}
+			let C = e.getComponent(r, u) ?? i, w = C.projectionType === 0 ? {
+				type: "orthographic",
+				zoom: C.zoom,
+				near: C.near,
+				far: C.far
+			} : {
+				type: "perspective",
+				fov: C.fov,
+				near: C.near,
+				far: C.far
+			};
+			t.set(o, {
+				worldTransform: {
+					position: {
+						x: c + b,
+						y: l + x,
+						z: _
+					},
+					rotation: {
+						x: C.rotX,
+						y: C.rotY,
+						z: C.rotZ
+					}
+				},
+				projection: w,
+				viewportId: o,
+				active: !0,
+				priority: C.priority
+			});
+		}
+		let o = /* @__PURE__ */ new Map();
+		for (let n of r) {
+			let r = n.id, i = e.getComponent(r, u);
+			if (!i || i.active !== 1) continue;
+			let a = h.get(r);
+			if (!a || !t.get(a)) continue;
+			let s = o.get(a), c = s === void 0 ? -Infinity : e.getComponent(s, u)?.priority ?? -Infinity;
+			i.priority >= c && o.set(a, r);
+		}
+		let c = e.hooks;
+		for (let [e, t] of o) {
+			let n = i.get(e);
+			n === void 0 ? c.callHook("camera:activate", {
+				viewportId: e,
+				entityId: t
+			}) : n !== t && c.callHook("camera:switch", {
+				viewportId: e,
+				from: n,
+				to: t
+			}), i.set(e, t);
+		}
+		for (let [e] of i) o.has(e) || (i.delete(e), c.callHook("camera:deactivate", { viewportId: e }));
+	});
+});
+//#endregion
+//#region ../kit/dist/plugin/index.js
+function P(e) {
+	function t(t) {
+		return e(t);
+	}
+	return t;
+}
+//#endregion
+//#region src/camera-core-plugin.ts
+var F = P(() => ({
+	name: "camera-core",
+	async setup(e) {
+		r(e), i(e), await e.use(N);
+	}
+}));
+//#endregion
+export { u as Camera, f as CameraBounds, F as CameraCorePlugin, l as CameraEmptyPathError, s as CameraErrorCodes, m as CameraPath, p as CameraShake, N as CameraSystem, c as CameraViewportNotFoundError, d as FollowTarget, g as cameraPathStore, h as cameraViewportMap };

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+import { EntityId } from '@gwenjs/core';
+import { Vec3 } from '@gwenjs/math';
+/** Easing function names accepted by CameraWaypoint and BlendOpts. */
+export type EasingName = "linear" | "easeIn" | "easeOut" | "easeInOut" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic";
+/** A single waypoint on a camera travelling path. Shared by camera2d and camera3d. */
+export interface CameraWaypoint {
+    /** Target position. 2D cameras use z = 0. */
+    position: Vec3;
+    /** Target rotation in euler radians. 2D cameras use only z. */
+    rotation?: Vec3;
+    /**
+     * If provided, overrides `rotation` — the camera orients toward this point/entity.
+     * Only meaningful for 3D cameras.
+     */
+    lookAt?: Vec3 | EntityId;
+    /** Target zoom (orthographic cameras). */
+    zoom?: number;
+    /** Target fov in radians (perspective cameras). */
+    fov?: number;
+    /** Transition duration in seconds. */
+    duration: number;
+    easing?: EasingName;
+}
+/** Options passed to `playPath()`. */
+export interface PathOpts {
+    loop?: boolean;
+    onComplete?: () => void;
+    onWaypoint?: (index: number) => void;
+}
+/** Runtime state for a camera path in progress — stored alongside the CameraPath component. */
+export interface CameraPathData {
+    waypoints: CameraWaypoint[];
+    opts: PathOpts;
+    /** Elapsed time in the current segment (seconds). */
+    elapsed: number;
+}
+/** Options for blend transitions between cameras. */
+export interface BlendOpts {
+    duration: number;
+    easing?: EasingName;
+    onComplete?: () => void;
+}
+/** Options accepted by `useFollowTarget`. */
+export interface FollowOpts {
+    lerp?: number;
+    offset?: Vec3;
+    /** 3D only: auto-orient toward the target. */
+    lookAt?: boolean;
+}
+/** Options accepted by `useShake`. */
+export interface ShakeOpts {
+    decay?: number;
+    maxOffset?: Vec3;
+}
+/** Handle returned by `useShake`. */
+export interface ShakeHandle {
+    /** Add trauma [0–1]. Values accumulate up to 1, then decay each frame. */
+    trauma(amount: number): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,YAAY,GACZ,aAAa,GACb,eAAe,GACf,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAErB,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,QAAQ,EAAE,IAAI,CAAC;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAC;IACzB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@gwenjs/camera-core",
+  "version": "0.1.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@gwenjs/core": "0.2.0",
+    "@gwenjs/math": "0.1.1",
+    "@gwenjs/kit": "0.2.0",
+    "@gwenjs/renderer-core": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}