@jgengine/shell 0.10.0 → 0.11.0

package/dist/world/WorldVfx.js

@@ -0,0 +1,184 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+const PARTICLE_COUNT = {
+    projectile: 7,
+    beam: 6,
+    nova: 14,
+    glow: 10,
+    spark: 12,
+};
+function planarDir() {
+    const angle = Math.random() * Math.PI * 2;
+    return new THREE.Vector3(Math.cos(angle), 0, Math.sin(angle));
+}
+function sphereDir() {
+    return new THREE.Vector3(Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random() * 2 - 1)
+        .normalize();
+}
+function makeParticles(kind) {
+    const count = PARTICLE_COUNT[kind];
+    const out = [];
+    for (let i = 0; i < count; i += 1) {
+        if (kind === "nova") {
+            out.push({ offset: new THREE.Vector3(), dir: planarDir(), speed: 1, size: 0.5 + Math.random() * 0.4, delay: 0 });
+        }
+        else if (kind === "spark") {
+            const dir = sphereDir();
+            dir.y = Math.abs(dir.y) * 0.6 + 0.2;
+            out.push({ offset: new THREE.Vector3(), dir, speed: 2.4 + Math.random() * 1.8, size: 0.28 + Math.random() * 0.22, delay: 0 });
+        }
+        else if (kind === "glow") {
+            out.push({
+                offset: planarDir().multiplyScalar(0.35 + Math.random() * 0.5),
+                dir: new THREE.Vector3(0, 1, 0),
+                speed: 0.5 + Math.random() * 0.6,
+                size: 0.55 + Math.random() * 0.5,
+                delay: Math.random() * 0.3,
+            });
+        }
+        else if (kind === "beam") {
+            out.push({ offset: new THREE.Vector3(), dir: new THREE.Vector3(), speed: 0, size: 0.45 + Math.random() * 0.3, delay: 0 });
+        }
+        else {
+            out.push({
+                offset: sphereDir().multiplyScalar(0.12),
+                dir: new THREE.Vector3(),
+                speed: 0,
+                size: 0.4 + Math.random() * 0.25,
+                delay: i * 0.05,
+            });
+        }
+    }
+    return out;
+}
+function useRadialTexture() {
+    return useMemo(() => {
+        const size = 64;
+        const canvas = document.createElement("canvas");
+        canvas.width = size;
+        canvas.height = size;
+        const c = canvas.getContext("2d");
+        if (c !== null) {
+            const gradient = c.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+            gradient.addColorStop(0, "rgba(255,255,255,1)");
+            gradient.addColorStop(0.35, "rgba(255,255,255,0.65)");
+            gradient.addColorStop(1, "rgba(255,255,255,0)");
+            c.fillStyle = gradient;
+            c.fillRect(0, 0, size, size);
+        }
+        const texture = new THREE.CanvasTexture(canvas);
+        texture.needsUpdate = true;
+        return texture;
+    }, []);
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function VfxItem({ event, texture }) {
+    const born = useRef(performance.now());
+    const sprites = useRef([]);
+    const ringRef = useRef(null);
+    const ringMat = useRef(null);
+    const beamMat = useRef(null);
+    const color = useMemo(() => new THREE.Color(event.color), [event.color]);
+    const from = useMemo(() => new THREE.Vector3(event.from[0], event.from[1] + 1, event.from[2]), [event.from]);
+    const to = useMemo(() => (event.to === undefined ? from.clone() : new THREE.Vector3(event.to[0], event.to[1] + 1, event.to[2])), [event.to, from]);
+    const radius = event.radius ?? 2.5;
+    const beam = useMemo(() => {
+        const delta = new THREE.Vector3().subVectors(to, from);
+        const length = Math.max(0.001, delta.length());
+        const mid = new THREE.Vector3().addVectors(from, to).multiplyScalar(0.5);
+        const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), delta.clone().normalize());
+        return { length, mid, quat };
+    }, [from, to]);
+    const particles = useMemo(() => makeParticles(event.kind), [event.kind]);
+    const scratch = useRef(new THREE.Vector3());
+    useFrame(() => {
+        const p = clamp01((performance.now() - born.current) / event.durationMs);
+        const kind = event.kind;
+        for (let i = 0; i < particles.length; i += 1) {
+            const sprite = sprites.current[i];
+            const particle = particles[i];
+            if (sprite === undefined || sprite === null || particle === undefined)
+                continue;
+            const pos = scratch.current;
+            let opacity = 0;
+            let scale = particle.size;
+            if (kind === "projectile") {
+                const travel = clamp01(p * 1.15 - particle.delay);
+                pos.copy(from).lerp(to, travel).add(particle.offset);
+                opacity = (1 - p) * (i === 0 ? 1 : 0.55);
+                scale = particle.size * (i === 0 ? 1 : 0.7);
+            }
+            else if (kind === "beam") {
+                pos.copy(from).lerp(to, i / Math.max(1, particles.length - 1));
+                opacity = (1 - p) * 0.8;
+            }
+            else if (kind === "nova") {
+                pos.set(event.from[0], event.from[1] + 0.4, event.from[2]).addScaledVector(particle.dir, radius * p);
+                opacity = (1 - p) * 0.9;
+            }
+            else if (kind === "glow") {
+                const local = clamp01(p - particle.delay);
+                pos.copy(from).add(particle.offset).addScaledVector(particle.dir, particle.speed * local);
+                opacity = Math.sin(clamp01(p) * Math.PI) * 0.9;
+                scale = particle.size * (0.8 + 0.3 * Math.sin(local * Math.PI));
+            }
+            else {
+                pos.copy(to).addScaledVector(particle.dir, particle.speed * p);
+                pos.y -= p * p * 1.4;
+                opacity = (1 - p) * 0.95;
+            }
+            sprite.position.copy(pos);
+            sprite.scale.set(scale, scale, 1);
+            const material = sprite.material;
+            material.opacity = opacity;
+        }
+        if (ringRef.current !== null && ringMat.current !== null) {
+            const s = Math.max(0.001, radius * p);
+            ringRef.current.scale.set(s, s, s);
+            ringMat.current.opacity = (1 - p) * 0.7;
+        }
+        if (beamMat.current !== null) {
+            beamMat.current.opacity = (1 - p) * 0.85;
+        }
+    });
+    return (_jsxs("group", { children: [particles.map((_, i) => (_jsx("sprite", { ref: (node) => {
+                    sprites.current[i] = node;
+                }, children: _jsx("spriteMaterial", { map: texture, color: color, transparent: true, depthWrite: false, depthTest: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 }) }, i))), event.kind === "nova" && (_jsxs("mesh", { ref: ringRef, position: [event.from[0], event.from[1] + 0.06, event.from[2]], rotation: [-Math.PI / 2, 0, 0], renderOrder: 998, children: [_jsx("ringGeometry", { args: [0.82, 1, 48] }), _jsx("meshBasicMaterial", { ref: ringMat, color: color, transparent: true, side: THREE.DoubleSide, depthWrite: false, depthTest: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] })), event.kind === "beam" && (_jsxs("mesh", { position: [beam.mid.x, beam.mid.y, beam.mid.z], quaternion: [beam.quat.x, beam.quat.y, beam.quat.z, beam.quat.w], renderOrder: 998, children: [_jsx("cylinderGeometry", { args: [0.12, 0.12, beam.length, 8, 1, true] }), _jsx("meshBasicMaterial", { ref: beamMat, color: color, transparent: true, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending, toneMapped: false, opacity: 0 })] }))] }));
+}
+/**
+ * Renders `combat.vfx` bursts as additive sprite-particle effects in the world scene. Auto-mounted by the
+ * player shell alongside the other world overlays; games emit effects via `ctx.scene.entity.vfx(...)`.
+ *
+ * @internal
+ */
+export function WorldSpellVfx({ tailMs = 200 }) {
+    const ctx = useGameContext();
+    const texture = useRadialTexture();
+    const [active, setActive] = useState([]);
+    const key = useRef(0);
+    const timers = useRef(new Set());
+    useEffect(() => {
+        const pending = timers.current;
+        const off = ctx.game.events.on("combat.vfx", (event) => {
+            const entry = { key: key.current++, event };
+            setActive((current) => [...current, entry]);
+            const timer = setTimeout(() => {
+                pending.delete(timer);
+                setActive((current) => current.filter((item) => item.key !== entry.key));
+            }, event.durationMs + tailMs);
+            pending.add(timer);
+        });
+        return () => {
+            off();
+            for (const timer of pending)
+                clearTimeout(timer);
+            pending.clear();
+        };
+    }, [ctx, tailMs]);
+    return (_jsx(_Fragment, { children: active.map((item) => (_jsx(VfxItem, { event: item.event, texture: texture }, item.key))) }));
+}

package/dist/world/entityPose.d.ts

@@ -10,5 +10,7 @@ export interface PoseSource {
     position: readonly [number, number, number];
     rotationY: number;
 }
+/** @internal */
 export declare function writeEntityPose(target: PoseWritable, source: PoseSource): void;
+/** @internal */
 export declare function posesEqual(a: PoseSource, b: PoseSource): boolean;

package/dist/world/entityPose.js

@@ -1,7 +1,9 @@
+/** @internal */
 export function writeEntityPose(target, source) {
     target.position.set(source.position[0], source.position[1], source.position[2]);
     target.rotation.y = source.rotationY;
 }
+/** @internal */
 export function posesEqual(a, b) {
     return (a.position[0] === b.position[0] &&
         a.position[1] === b.position[1] &&

package/dist/world/floatTextStyle.d.ts

@@ -11,4 +11,5 @@ export interface FloatTextStyle {
     fontWeight: number;
     glow: string;
 }
+/** @internal */
 export declare function resolveFloatTextStyle(info: FloatTextInfo): FloatTextStyle;

package/dist/world/floatTextStyle.js

@@ -12,6 +12,7 @@ const ELEMENT_COLORS = {
     holy: "#fef08a",
     void: "#c084fc",
 };
+/** @internal */
 export function resolveFloatTextStyle(info) {
     const crit = info.crit === true || info.hitType === "crit";
     let color;

package/dist/world/telegraphPulse.d.ts

@@ -1 +1,2 @@
+/** @internal */
 export declare function telegraphPulseOpacity(bornMs: number, windupMs: number, nowMs: number): number;

package/dist/world/telegraphPulse.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function telegraphPulseOpacity(bornMs, windupMs, nowMs) {
     const progress = Math.max(0, Math.min(1, (nowMs - bornMs) / Math.max(1, windupMs)));
     return 0.45 + 0.5 * progress;

package/dist/world/worldBarSamples.d.ts

@@ -16,6 +16,7 @@ export interface Projectable {
     y: number;
     z: number;
 }
+/** @internal */
 export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
     matrixWorldInverse: unknown;
     projectionMatrix: unknown;
@@ -23,6 +24,30 @@ export declare function collectWorldBarSamples(ctx: GameContext, statId: string,
     width: number;
     height: number;
 }, into: WorldBarSample[], project: Projectable, maxDistance?: number): number;
+/** One entity's projected nameplate: screen `x`/`y`, display `name`, health `percent` (or `null` when statless), and world `distance` from the player. */
+export interface NameplateSample {
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    /** Health-stat fraction 0..1, or `null` when the entity carries no `statId` stat (name-only nameplate). */
+    percent: number | null;
+    distance: number;
+}
+/**
+ * Projects every non-local, role/distance-filtered entity into `into` as a
+ * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
+ * own renderer by calling this directly instead of the component.
+ * @internal
+ */
+export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
+    matrixWorldInverse: unknown;
+    projectionMatrix: unknown;
+}, viewport: {
+    width: number;
+    height: number;
+}, into: NameplateSample[], project: Projectable, maxDistance?: number): number;
+/** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;
     height: number;

package/dist/world/worldBarSamples.js

@@ -1,4 +1,5 @@
 import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
+/** @internal */
 export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60) {
     into.length = 0;
     const playerId = ctx.player.userId;
@@ -28,6 +29,43 @@ export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole,
     }
     return into.length;
 }
+/**
+ * Projects every non-local, role/distance-filtered entity into `into` as a
+ * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
+ * own renderer by calling this directly instead of the component.
+ * @internal
+ */
+export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40) {
+    into.length = 0;
+    const playerId = ctx.player.userId;
+    const player = ctx.scene.entity.get(playerId);
+    for (const entity of ctx.scene.entity.list()) {
+        if (entity.id === playerId)
+            continue;
+        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+            continue;
+        const distance = player === null
+            ? 0
+            : Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]);
+        if (player !== null && distance > maxDistance)
+            continue;
+        const stat = ctx.scene.entity.stats.get(entity.id, statId);
+        let percent = null;
+        if (stat !== null) {
+            const range = stat.max - stat.min;
+            percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+        }
+        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
+        project.project(camera);
+        if (project.z < -1 || project.z > 1)
+            continue;
+        const x = (project.x * 0.5 + 0.5) * viewport.width;
+        const y = (-project.y * 0.5 + 0.5) * viewport.height;
+        into.push({ id: entity.id, name: entity.name, x, y, percent, distance });
+    }
+    return into.length;
+}
+/** @internal */
 export function paintWorldBarSamples(canvas, samples, dpr, barWidthPx = 112, barHeightPx = 10) {
     const g = canvas.getContext("2d");
     if (g === null)

package/dist/worldSky.d.ts

@@ -0,0 +1,5 @@
+import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
+/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+export declare function resolveWorldSky(world: WorldFeature | undefined): SkyEnvironmentDescriptor | undefined;
+/** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */
+export declare function colorFromId(id: string): string;

package/dist/worldSky.js

@@ -0,0 +1,11 @@
+/** The world's declared sky, when its world feature is an environment with one (#196.1). @internal */
+export function resolveWorldSky(world) {
+    return world?.kind === "environment" ? world.sky : undefined;
+}
+/** Deterministic HSL color from a stable instance id (default entity/object tint). @internal */
+export function colorFromId(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1)
+        hash = (hash * 31 + id.charCodeAt(index)) >>> 0;
+    return `hsl(${hash % 360}, 65%, 55%)`;
+}

package/dist/worldSync.d.ts

@@ -6,5 +6,6 @@ import type { GameRuntimeFeeds } from "@jgengine/core/runtime/transport";
  * of a locally-simulated one. Pure and transport-agnostic — the backend's `feeds.subscribeServer` is the only
  * dependency; returns the unsubscribe. The shell attaches this (and gates its local sim) when the game's adapter
  * opts into `authority: "server"`.
- */
+  * @internal
+  */
 export declare function attachWorldSync(feeds: Pick<GameRuntimeFeeds, "subscribeServer">, serverId: string, ctx: Pick<GameContext, "hydrate">): () => void;

package/dist/worldSync.js

@@ -5,7 +5,8 @@ import { createWorldMirror } from "@jgengine/core/runtime/worldMirror";
  * of a locally-simulated one. Pure and transport-agnostic — the backend's `feeds.subscribeServer` is the only
  * dependency; returns the unsubscribe. The shell attaches this (and gates its local sim) when the game's adapter
  * opts into `authority: "server"`.
- */
+  * @internal
+  */
 export function attachWorldSync(feeds, serverId, ctx) {
     const mirror = createWorldMirror(ctx);
     return feeds.subscribeServer(serverId, (view) => {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "exports": {
     "./weather": {
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0",
-    "@jgengine/react": "^0.10.0",
-    "@jgengine/ws": "^0.10.0"
+    "@jgengine/core": "^0.11.0",
+    "@jgengine/react": "^0.11.0",
+    "@jgengine/ws": "^0.11.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+Capture only decisions that change architecture:
+
+- player point of view and controls
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and art direction
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+3. Open the linked reference only for a deeper recipe or trap.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.