@energy8platform/game-engine 0.24.0 → 0.26.0

package/src/slot/devtools/panelClient.ts

@@ -0,0 +1,126 @@
+// packages/game-engine/src/slot/devtools/panelClient.ts
+//
+// The harness "Reels" sidebar panel client. Built as a SELF-CONTAINED browser ESM
+// (dist/reel-panel-client.js) and served by the harness at /__harness/panel/reels.js.
+// Default-exports the HarnessPanelMount the core client calls.
+//
+// It seeds its controls from the running game's config (received over the bus), applies
+// every edit LIVE (posts a patch → the game's reel bridge calls system.update), and
+// offers a "Copy config" button that emits the paste-ready overrides snippet.
+
+import type { HarnessPanelMount } from '@energy8platform/harness/panel';
+import type { ReelSystemConfig } from '../config/ReelSystemConfig';
+import { buildControlPanel } from './controlPanel';
+import { REEL_FIELD_SCHEMA, type SectionKey } from './fieldSchema';
+import { emitReelConfigTs } from './configDiff';
+import { REEL_APPLY, REEL_READY, REEL_REQUEST, type ReelDevMessage } from './protocol';
+
+/** Config the harness plugin passes via ctx.config, e.g. { sections: { geometry: false } }. */
+interface ReelPanelConfig {
+  /** Per-section visibility. Missing key = shown. */
+  sections?: Partial<Record<SectionKey, boolean>>;
+}
+
+const CSS = `
+.e8rp-wait { color: #6b7480; font-size: 12px; line-height: 1.6; padding: 8px 2px; }
+.e8rp-bar { display: flex; gap: 8px; margin-bottom: 12px; }
+.e8rp-bar button {
+  flex: 1 1 0; background: #1c2128; color: #cfd5dd; border: 1px solid #3a414c; border-radius: 8px;
+  padding: 8px; font: inherit; font-size: 12px; font-weight: 600; cursor: pointer;
+}
+.e8rp-bar button:hover { border-color: #4b5563; color: #fff; }
+.e8rp-status { font-size: 11px; color: #6b7480; min-height: 14px; margin-bottom: 8px; }
+.e8rp-controls .panel-section { border-top: 1px solid #1d222a; }
+.e8rp-controls .section-head {
+  width: 100%; text-align: left; background: transparent; border: 0; color: #aab2bd;
+  font: inherit; font-size: 11px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase;
+  padding: 10px 2px 6px; cursor: pointer;
+}
+.e8rp-controls .section-body { display: flex; flex-direction: column; gap: 2px; padding-bottom: 6px; }
+.e8rp-controls .control {
+  display: flex; align-items: center; gap: 8px; padding: 4px 2px; font-size: 12px; color: #d3d8df;
+}
+.e8rp-controls .control-label { flex: 1 1 auto; }
+.e8rp-controls .control-value { width: 34px; text-align: right; color: #828b98; font-variant-numeric: tabular-nums; }
+.e8rp-controls input[type=range] { flex: 0 0 120px; }
+.e8rp-controls select { background: #1c2128; color: #e9ecf1; border: 1px solid #3a414c; border-radius: 6px; padding: 3px 6px; font: inherit; font-size: 12px; }
+.e8rp-controls .control-toggle { justify-content: space-between; }
+`;
+
+function injectCss(): void {
+  if (document.getElementById('e8-reel-panel-css')) return;
+  const style = document.createElement('style');
+  style.id = 'e8-reel-panel-css';
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+
+const mount: HarnessPanelMount = (ctx) => {
+  injectCss();
+  const root = ctx.root;
+
+  // Section visibility from the plugin (reelDevtoolsPlugin({ sections: { geometry: false } })).
+  const panelCfg = (ctx.config ?? {}) as ReelPanelConfig;
+  const sectionOn = panelCfg.sections ?? {};
+  const schema = REEL_FIELD_SCHEMA.filter((s) => s.key == null || sectionOn[s.key] !== false);
+  root.innerHTML = '<p class="e8rp-wait">Waiting for the game’s reel bridge…<br/>(the game must call <code>mountReelDevBridge</code>.)</p>';
+
+  let working: ReelSystemConfig | null = null;
+  let built = false;
+
+  const status = (msg: string): void => {
+    const el = root.querySelector<HTMLElement>('.e8rp-status');
+    if (el) el.textContent = msg;
+  };
+  const copy = (text: string, label: string): void => {
+    navigator.clipboard
+      ?.writeText(text)
+      .then(() => status(`${label} copied`))
+      .catch(() => status('Copy failed'));
+  };
+
+  const buildUi = (config: ReelSystemConfig): void => {
+    working = structuredClone(config);
+    root.innerHTML = '';
+
+    const bar = document.createElement('div');
+    bar.className = 'e8rp-bar';
+    const copyTs = document.createElement('button');
+    copyTs.textContent = 'Copy config';
+    copyTs.addEventListener('click', () => working && copy(emitReelConfigTs(working), 'TS config'));
+    const copyJson = document.createElement('button');
+    copyJson.textContent = 'Copy JSON';
+    copyJson.addEventListener('click', () => working && copy(JSON.stringify(working, null, 2), 'JSON'));
+    bar.append(copyTs, copyJson);
+
+    const statusEl = document.createElement('div');
+    statusEl.className = 'e8rp-status';
+
+    const controls = document.createElement('div');
+    controls.className = 'e8rp-controls';
+
+    root.append(bar, statusEl, controls);
+
+    buildControlPanel(controls, {
+      config: working,
+      schema,
+      onChange: () => {
+        ctx.post({ type: REEL_APPLY, patch: working as ReelSystemConfig } satisfies ReelDevMessage);
+      },
+    });
+    built = true;
+  };
+
+  ctx.on((raw) => {
+    const msg = raw as ReelDevMessage | undefined;
+    if (msg && typeof msg === 'object' && msg.type === REEL_READY) buildUi(msg.config);
+  });
+
+  // Ask the game for its config (covers the game-loaded-first case); retry a couple times.
+  const request = (): void => ctx.post({ type: REEL_REQUEST } satisfies ReelDevMessage);
+  request();
+  window.setTimeout(() => !built && request(), 400);
+  window.setTimeout(() => !built && request(), 1200);
+};
+
+export default mount;

package/src/slot/devtools/protocol.ts

@@ -0,0 +1,29 @@
+// packages/game-engine/src/slot/devtools/protocol.ts
+//
+// The postMessage protocol between the harness reel panel (parent window) and the
+// reel dev bridge (game iframe). Pure constants + message types — no deps.
+
+import type { DeepPartial, ReelSystemConfig } from '../config/ReelSystemConfig';
+
+/** Game → panel: announces the current resolved config (on mount + on request). */
+export interface ReelReadyMessage {
+  type: 'e8:reel:ready';
+  config: ReelSystemConfig;
+}
+
+/** Panel → game: apply a partial config live (system.update). */
+export interface ReelApplyMessage {
+  type: 'e8:reel:apply';
+  patch: DeepPartial<ReelSystemConfig>;
+}
+
+/** Panel → game: (re)request the current config, e.g. when the panel opens late. */
+export interface ReelRequestMessage {
+  type: 'e8:reel:request';
+}
+
+export type ReelDevMessage = ReelReadyMessage | ReelApplyMessage | ReelRequestMessage;
+
+export const REEL_READY = 'e8:reel:ready';
+export const REEL_APPLY = 'e8:reel:apply';
+export const REEL_REQUEST = 'e8:reel:request';

package/src/slot/devtools/reelDevBridge.ts

@@ -0,0 +1,80 @@
+// packages/game-engine/src/slot/devtools/reelDevBridge.ts
+//
+// Game-side opt-in bridge for the harness reel panel. Call once, after creating the
+// ReelSystem, to let the harness sidebar tune the reels LIVE:
+//
+//   import { mountReelDevBridge } from '@energy8platform/game-engine/devtools';
+//   const bridge = mountReelDevBridge({ system });
+//
+// It announces the system's current config to the parent (the harness wrapper) and
+// applies incoming patches via `system.update()`. Changes are EPHEMERAL — they live
+// only in this running iframe and are lost on reload. To persist, use the panel's
+// "Copy config" button and paste the snippet into your game's reel config.
+//
+// No-op outside an iframe (window.parent === window), so it is safe to leave in.
+
+import type { DeepPartial, ReelSystemConfig } from '../config/ReelSystemConfig';
+import { REEL_APPLY, REEL_READY, REEL_REQUEST, type ReelDevMessage } from './protocol';
+
+/** Minimal ReelSystem surface the bridge needs (keeps it decoupled/testable). */
+export interface ReelDevBridgeTarget {
+  readonly config: ReelSystemConfig;
+  update(partial: DeepPartial<ReelSystemConfig>): void;
+}
+
+export interface ReelDevBridgeOptions {
+  system: ReelDevBridgeTarget;
+  /** postMessage targetOrigin for the parent. Default '*' (dev harness, same-origin). */
+  targetOrigin?: string;
+  /**
+   * Guard: only mount when true. Defaults to `import.meta.env?.DEV` when available,
+   * else true. Pass `false` to hard-disable.
+   */
+  enabled?: boolean;
+}
+
+export interface ReelDevBridge {
+  /** Re-announce the current config to the parent. */
+  announce(): void;
+  /** Detach the message listener. */
+  dispose(): void;
+}
+
+function defaultEnabled(): boolean {
+  try {
+    // vite injects import.meta.env.DEV; guard so non-vite builds don't throw.
+    const env = (import.meta as unknown as { env?: { DEV?: boolean } }).env;
+    return env?.DEV ?? true;
+  } catch {
+    return true;
+  }
+}
+
+export function mountReelDevBridge(opts: ReelDevBridgeOptions): ReelDevBridge {
+  const enabled = opts.enabled ?? defaultEnabled();
+  const noop: ReelDevBridge = { announce: () => {}, dispose: () => {} };
+  if (!enabled || typeof window === 'undefined' || window.parent === window) return noop;
+
+  const origin = opts.targetOrigin ?? '*';
+  const { system } = opts;
+
+  const announce = (): void => {
+    window.parent.postMessage({ type: REEL_READY, config: system.config } satisfies ReelDevMessage, origin);
+  };
+
+  const onMessage = (e: MessageEvent): void => {
+    if (e.source !== window.parent) return;
+    const msg = e.data as ReelDevMessage | undefined;
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === REEL_APPLY) system.update(msg.patch);
+    else if (msg.type === REEL_REQUEST) announce();
+  };
+
+  window.addEventListener('message', onMessage);
+  announce(); // cover the panel-already-open case
+
+  return {
+    announce,
+    dispose: () => window.removeEventListener('message', onMessage),
+  };
+}