@jgengine/react 0.10.0 → 0.12.0

package/skills/jgengine-ui/capabilities.md

@@ -0,0 +1,211 @@
+<!-- GENERATED by scripts/gen-capability-index.ts — do not edit. Regenerate: bun run gen:capabilities -->
+
+# jgengine-ui — capability index
+
+Reach for these before hand-rolling. Each row is *the thing you need* → *the primitive that already does it*.
+
+## action-bar — optional skinned action-bar composition over the headless model — games own chrome
+
+- `ActionBar` (function) · `import { ActionBar } from "@jgengine/react"`
+
+## action-bar-chrome — accessible grid/list toolbar renderer over an action-bar model with swappable item chrome
+
+- `ActionBarChrome` (function) · `import { ActionBarChrome } from "@jgengine/react"`
+
+## action-bar-model — headless action-collection model with focus, hover, keyboard, and hotkey routing
+
+- `useActionBar` (function) · `import { useActionBar } from "@jgengine/react"`
+
+## action-button — cooldown/cost/hotkey action button with complete interaction states
+
+- `ActionButton` (function) · `import { ActionButton } from "@jgengine/react"`
+
+## action-from-ability-slot — adapt a combat ability-kit snapshot into an action-bar action def
+
+- `actionFromAbilitySlot` (function) · `import { actionFromAbilitySlot } from "@jgengine/react"`
+
+## action-tooltip — structured action tooltip body (title, cost, cooldown, blocking notes)
+
+- `ActionTooltip` (function) · `import { ActionTooltip } from "@jgengine/react"`
+
+## clock-format — format a signed time gap like a race split (+/- m:ss.ff)
+
+- `formatDelta` (function) · `import { formatDelta } from "@jgengine/core/ui"`
+- `formatDuration` (function) · `import { formatDuration } from "@jgengine/core/ui"`
+
+## controls-list — keybind-derived control legend that hides on touch
+
+- `ControlsList` (function) · `import { ControlsList } from "@jgengine/react"`
+
+## default-look — one field that lights a scene like a shipped game (opt out with "flat")
+
+- `LookPreset` (type) · `import { LookPreset } from "@jgengine/core/ui"`
+
+## distance-format — render meters as m or km for HUD stats, telemetry, and range readouts
+
+- `formatDistance` (function) · `import { formatDistance } from "@jgengine/core/ui"`
+
+## entity-portrait — selectable entity portrait tile with vitals and selected/focus states
+
+- `EntityPortrait` (function) · `import { EntityPortrait } from "@jgengine/react"`
+
+## entity-render-cues — live velocity/bob/fire/reload/hit/death cues for a custom renderEntity or viewmodel component
+
+- `useEntityRenderCues` (function) · `import { useEntityRenderCues } from "@jgengine/shell/render/useEntityRenderCues"`
+
+## entity-summary — primary selected-entity detail panel (name, tags, vitals)
+
+- `EntitySummary` (function) · `import { EntitySummary } from "@jgengine/react"`
+
+## event-meter-hud — render a core event/heat meter's live value, fraction, tier, and ready state in a HUD gauge
+
+- `useEventMeter` (function) · `import { useEventMeter } from "@jgengine/react"`
+
+## heightfield-mesh-update — in-place partial update of a displaced ground plane mesh
+
+- `displaceHeightfieldGeometry` (function) · `import { displaceHeightfieldGeometry } from "@jgengine/shell/terrain"`
+
+## hud-canvas — the HUD root surface — design-resolution scaling plus live panel-placement editing (F2+C)
+
+- `HudCanvas` (function) · `import { HudCanvas } from "@jgengine/react"`
+
+## hud-clock — in-game time-of-day readout bound to the sim clock
+
+- `Clock` (function) · `import { Clock } from "@jgengine/react"`
+
+## hud-coins — currency counter widget bound to a currency id
+
+- `Coins` (function) · `import { Coins } from "@jgengine/react"`
+
+## hud-frame — optional framed panel skins (glass/plate/retro/themed) — games own product chrome
+
+- `HudFrame` (function) · `import { HudFrame } from "@jgengine/react"`
+
+## hud-hotbar — optional inventory hotbar building block — games own slot chrome
+
+- `Hotbar` (function) · `import { Hotbar } from "@jgengine/react"`
+
+## hud-icons — painted-icon treatment for hotbar/action slots — glyph + gradient + count badge
+
+- `IconSchool` (type) · `import { IconSchool } from "@jgengine/react"`
+
+## hud-layout — persistent, live-editable HUD panel layout state for `HudCanvas`
+
+- `useHudLayout` (function) · `import { useHudLayout } from "@jgengine/react"`
+
+## hud-layout-persist — inject a host callback so canvas HUD edits commit into the scene document
+
+- `HudLayoutPersistProvider` (function) · `import { HudLayoutPersistProvider } from "@jgengine/react"`
+
+## hud-layout-persist-hook — read the host panel-commit port from a HUD layout widget
+
+- `useHudLayoutPersist` (function) · `import { useHudLayoutPersist } from "@jgengine/react"`
+
+## hud-panel — anchored HUD slot — drop any widget in a named, player-movable panel
+
+- `HudPanel` (function) · `import { HudPanel } from "@jgengine/react"`
+
+## hud-slots — atomic themed equipment/weapon/armor/potion slot grids with painted icons
+
+- `SlotItem` (interface) · `import { SlotItem } from "@jgengine/react"`
+
+## hud-stat-bar — optional stat-bound bar building block (health, mana, stamina) — prefer game-owned chrome
+
+- `StatBar` (function) · `import { StatBar } from "@jgengine/react"`
+
+## hud-theme — game-authored token object for bars, frames, slots, and minimap ring
+
+- `HudThemePalette` (interface) · `import { HudThemePalette } from "@jgengine/react"`
+
+## hud-vitals — atomic purpose-named vitals bars (token-themed parts, not a finished HUD)
+
+- `BarTokens` (interface) · `import { BarTokens } from "@jgengine/react"`
+- `barTokens` (function) · `import { barTokens } from "@jgengine/react"`
+
+## key-hint — keyboard/mouse control hint that hides itself on touch
+
+- `KeyHint` (function) · `import { KeyHint } from "@jgengine/react"`
+
+## keycap — styled keyboard/mouse key cap for control hints
+
+- `Keycap` (function) · `import { Keycap } from "@jgengine/react"`
+
+## live-markers — a self-ticking MarkerSet kept in sync from the live scene each HUD tick — pass a rebuild(markers, ctx) that clears+repopulates, no hand-rolled setInterval
+
+- `useLiveMarkers` (function) · `import { useLiveMarkers } from "@jgengine/react"`
+
+## minimap — framed circular minimap with terrain bake, fog, markers, and facing arrow
+
+- `Minimap` (function) · `import { Minimap } from "@jgengine/react"`
+
+## minimap-chrome — ring frame plus edge-clamped, heading-aware marker dots to nest inside a game's own `<svg>`
+
+- `MinimapChrome` (function) · `import { MinimapChrome } from "@jgengine/react"`
+
+## minimap-panel — circular minimap with zone label, clock, and compass composed together
+
+- `MinimapPanel` (function) · `import { MinimapPanel } from "@jgengine/react"`
+
+## minimap-track-hud — horizontal linear track minimap (corridor/route progress) — colored zone spans and gate/player pips positioned by 0..1 fraction, sharing chrome with the radial Minimap
+
+- `MinimapTrack` (function) · `import { MinimapTrack } from "@jgengine/react"`
+
+## nameplates — billboarded name + HP bar over nearby entities
+
+- `WorldNameplates` (function) · `import { WorldNameplates } from "@jgengine/shell/world/WorldHud"`
+
+## ordinal-format — format a placement number as 1st/2nd/3rd for HUD ranks
+
+- `formatOrdinal` (function) · `import { formatOrdinal } from "@jgengine/core/ui"`
+
+## placement-ghost — render valid/invalid placement preview mesh
+
+- `PlacementGhost` (function) · `import { PlacementGhost } from "@jgengine/shell/structures"`
+
+## popover — viewport-flipping, viewport-clamped anchored popover/tooltip shell
+
+- `Popover` (function) · `import { Popover } from "@jgengine/react"`
+
+## resolve-game-look — expand a look preset into concrete lighting/backdrop/post knobs
+
+- `resolveGameLook` (function) · `import { resolveGameLook } from "@jgengine/core/ui"`
+
+## selection-collection — accessible portrait-strip / group-chip renderer over a selection model
+
+- `SelectionCollectionChrome` (function) · `import { SelectionCollectionChrome } from "@jgengine/react"`
+
+## selection-group-chip — same-kind selection chip (icon + count) for a grouped selection
+
+- `SelectionGroupChip` (function) · `import { SelectionGroupChip } from "@jgengine/react"`
+
+## selection-model — headless multi-entity selection model with primary focus, grouping, and virtualization
+
+- `useSelectionView` (function) · `import { useSelectionView } from "@jgengine/react"`
+
+## selection-panel — optional selection-panel composition: summary + portrait strip / group chips
+
+- `SelectionPanel` (function) · `import { SelectionPanel } from "@jgengine/react"`
+
+## speed-format — render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
+
+- `formatSpeed` (function) · `import { formatSpeed } from "@jgengine/core/ui"`
+
+## start-screen — headless title/attract overlay the game fills and skins
+
+- `StartScreen` (function) · `import { StartScreen } from "@jgengine/react"`
+
+## studio-stage — cinematic lighting rig + backdrop + turntable for parametric studios
+
+- `StudioStage` (function) · `import { StudioStage } from "@jgengine/shell/scene/StudioStage"`
+
+## transform-gizmo — in-game select/move/rotate/scale gizmo
+
+- `TransformGizmo` (const) · `import { TransformGizmo } from "@jgengine/shell/structures"`
+
+## vital-bar — compact current/max vital meter for an entity summary
+
+- `VitalBar` (function) · `import { VitalBar } from "@jgengine/react"`
+
+## world-object-highlights — ground-ring highlight over every selected placed object
+
+- `WorldObjectHighlights` (function) · `import { WorldObjectHighlights } from "@jgengine/shell/world/WorldHud"`

package/skills/jgengine-ui/recipes/portable-minimap.md

@@ -0,0 +1,150 @@
+# Add the minimap to an existing React game
+
+Use this recipe when a React game already owns its entities in an array, ECS
+query, Zustand/Redux-style store, or another observable collection. JGengine
+only needs a display view of those records; do not copy them into a
+`MarkerSet`.
+
+## Install
+
+Keep the React and React DOM versions already used by the project, then add the
+two focused JGengine packages:
+
+```sh
+bun add @jgengine/core @jgengine/react
+```
+
+The minimap imports neither Three.js nor React Three Fiber and does not require
+`GameProvider`.
+
+## Static entity arrays
+
+Project an existing array directly. Keep the array stable with the same memo or
+selector the project already uses.
+
+```tsx
+import { useMemo } from "react";
+import { Minimap } from "@jgengine/react/map";
+
+interface Unit {
+  id: string;
+  x: number;
+  z: number;
+  team: "ally" | "enemy";
+}
+
+export function MapHud({
+  units,
+  cameraTarget,
+}: {
+  units: readonly Unit[];
+  cameraTarget: { x: number; z: number };
+}) {
+  const markers = useMemo(
+    () =>
+      units.map((unit) => ({
+        id: unit.id,
+        position: [unit.x, 0, unit.z] as const,
+        kind: unit.team,
+      })),
+    [units],
+  );
+
+  return (
+    <Minimap
+      markers={markers}
+      center={[cameraTarget.x, cameraTarget.z]}
+      worldRadius={120}
+      className="game-minimap"
+    />
+  );
+}
+```
+
+Only `id` and `position` are required. `kind`, `label`, `heading`, and `meta`
+are optional display data; lifecycle timestamps are not part of this view.
+
+## Observable external store
+
+Create the adapter once per store. The source caches its projected marker array
+until the external store emits, so React snapshot reads do not remap the world
+on every frame.
+
+```tsx
+import { useMemo } from "react";
+import { createMarkerSource } from "@jgengine/core/world/markers";
+import { Minimap } from "@jgengine/react/map";
+
+interface Unit {
+  id: string;
+  x: number;
+  z: number;
+  team: string;
+  name: string;
+}
+
+interface ExistingWorldStore {
+  subscribe(listener: () => void): () => void;
+  getState(): { units: readonly Unit[] };
+}
+
+export function ExistingGameMinimap({
+  world,
+  cameraTarget,
+}: {
+  world: ExistingWorldStore;
+  cameraTarget: { x: number; z: number };
+}) {
+  const markers = useMemo(
+    () =>
+      createMarkerSource({
+        subscribe: (listener) => world.subscribe(listener),
+        getSnapshot: () => world.getState().units,
+        project: (unit) => ({
+          id: unit.id,
+          position: [unit.x, 0, unit.z] as const,
+          kind: unit.team,
+          label: unit.name,
+        }),
+      }),
+    [world],
+  );
+
+  return (
+    <Minimap
+      markers={markers}
+      center={[cameraTarget.x, cameraTarget.z]}
+      worldRadius={120}
+    />
+  );
+}
+```
+
+For SSR, make the store's first client snapshot match the server snapshot. When
+they differ structurally, pass `getServerSnapshot` to `createMarkerSource` and
+read the same serialized initial units used to hydrate the external store.
+
+## Ownership
+
+The existing project still owns entities, updates, persistence, simulation,
+camera, renderer, input, scheduling, and the subscription. JGengine owns only
+the cached entity-to-marker projection, core world-to-map projection math, and
+the React SVG presentation. Save and restore the project's unit state as usual;
+markers are derived data and need no parallel save format.
+
+Use `kindStyles`, `className`, and `style` to skin the production `Minimap`.
+When the project owns every chrome element, compose `MinimapChrome` inside its
+own SVG instead of adopting the framed default.
+
+## Common traps
+
+- Keep `getSnapshot()` array identity stable until `subscribe()` emits. This is
+  the React external-store contract.
+- Create `createMarkerSource` outside render or in `useMemo`; recreating it each
+  render discards its projection cache.
+- Pass world coordinates, not Three.js screen coordinates. Marker positions are
+  `[x, y, z]`; the minimap projects X/Z.
+- Do not poll the source from a render loop. Notify subscribers when the
+  caller-owned collection changes.
+- Do not add `createdAt` or `expiresAt` unless the project intentionally adopts
+  `MarkerSet` lifecycle behavior.