@energy8platform/game-engine 0.10.11 → 0.12.0

package/README.md

@@ -35,7 +35,6 @@ A casino game engine built on [PixiJS v8](https://pixijs.com/) and [@energy8plat
 npm install pixi.js @energy8platform/game-sdk @energy8platform/game-engine
 
 # Optional peer dependencies
-npm install @pixi/ui @pixi/layout yoga-layout    # UI components (Layout, Panel, ScrollContainer)
 npm install @pixi/sound                           # Audio
 npm install @esotericsoftware/spine-pixi-v8       # Spine animations
 npm install react react-dom react-reconciler      # React integration
@@ -88,9 +87,6 @@ bootstrap();
 | --- | --- | --- |
 | `pixi.js` | `^8.16.0` | Yes |
 | `@energy8platform/game-sdk` | `^2.7.0` | Yes |
-| `@pixi/ui` | `^2.3.0` | Optional — Button, ScrollContainer, ProgressBar |
-| `@pixi/layout` | `^3.2.0` | Optional — Layout, Panel (Yoga flexbox) |
-| `yoga-layout` | `^3.0.0` | Optional — peer dep of `@pixi/layout` |
 | `@pixi/sound` | `^6.0.0` | Optional — audio |
 | `@esotericsoftware/spine-pixi-v8` | `~4.2.0` | Optional — Spine animations |
 | `react`, `react-dom` | `>=18.0.0` | Optional — ReactScene |
@@ -104,10 +100,10 @@ import { GameApplication } from '@energy8platform/game-engine';             // f
 import { Scene, SceneManager } from '@energy8platform/game-engine/core';
 import { AssetManager } from '@energy8platform/game-engine/assets';
 import { AudioManager } from '@energy8platform/game-engine/audio';
-import { Button, Label, Modal, Layout, ScrollContainer, Panel, Toast } from '@energy8platform/game-engine/ui';
+import { FlexContainer, Button, Label, Panel, Modal, Layout, ScrollContainer, Toast, ProgressBar, BalanceDisplay, WinDisplay, Slider, Toggle, resolveView } from '@energy8platform/game-engine/ui';
 import { Tween, Timeline, Easing, SpriteAnimation } from '@energy8platform/game-engine/animation';
 import { DevBridge, FPSOverlay } from '@energy8platform/game-engine/debug';
-import { ReactScene, createPixiRoot, useSDK, useViewport } from '@energy8platform/game-engine/react';
+import { ReactScene, extendPixiElements, extendUIElements, useSDK, useViewport } from '@energy8platform/game-engine/react';
 import { defineGameConfig } from '@energy8platform/game-engine/vite';
 import { LuaEngine, ActionRouter } from '@energy8platform/game-engine/lua';
 ```
@@ -396,17 +392,65 @@ SpineHelper.setSkin(spine, 'warrior');
 
 ## UI Components
 
-> Requires `@pixi/ui` and `@pixi/layout` + `yoga-layout` as peer dependencies. Import from `@energy8platform/game-engine/ui`.
->
-> For components not wrapped by the engine (`Slider`, `CheckBox`, `Input`, `Select`, etc.), import directly from `@pixi/ui`.
+> Built-in UI system with zero external dependencies. No `@pixi/ui`, `@pixi/layout`, or `yoga-layout` required. Import from `@energy8platform/game-engine/ui`.
 
-### Layout
+### Asset Skinning (`ViewInput`)
+
+Every visual component supports custom artwork via the `ViewInput` type:
+
+```typescript
+type ViewInput = string | Texture | Container;
+```
+
+- `string` — texture name, resolved via `Sprite.from()` from the asset manager
+- `Texture` — wrapped in a `Sprite`
+- `Container` — used as-is (NineSliceSprite, AnimatedSprite, custom artwork, etc.)
+
+If no custom view is provided, components fall back to Graphics-based rendering (colors, rounded rects). This means you can prototype with Graphics and later swap to production art with no API changes.
+
+### FlexContainer
+
+Lightweight flexbox-like layout container. Children added via `addChild()` automatically participate in flex layout.
+
+```typescript
+const toolbar = new FlexContainer({
+  direction: 'row',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  gap: 16,
+  padding: 12,
+});
+toolbar.addChild(button1);                       // auto flex layout
+toolbar.addChild(button2);
+toolbar.addFlexChild(spacer, { flexGrow: 1 });   // with flex config
+toolbar.resize(800, 60);
+```
+
+**FlexItemConfig** — per-child options passed via `addFlexChild(child, config)` or JSX props:
 
-Responsive flexbox container powered by `@pixi/layout`. Supports `horizontal`, `vertical`, `grid`, `wrap` modes with alignment, padding, gap, anchoring, and viewport breakpoints.
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `flexGrow` | `number` | `0` | Flex grow factor |
+| `flexShrink` | `number` | `1` | Flex shrink factor (`0` = don't shrink when content overflows) |
+| `alignSelf` | `'auto' \| 'start' \| 'center' \| 'end' \| 'stretch'` | `'auto'` | Override parent's `alignItems` for this child |
+| `flexExclude` | `boolean` | `false` | Exclude from flex layout (like `position: absolute`) |
+| `layoutWidth` | `number` | — | Explicit width override for layout calculations |
+| `layoutHeight` | `number` | — | Explicit height override for layout calculations |
 
 ```typescript
-import { Layout } from '@energy8platform/game-engine/ui';
+// Fixed item that won't shrink + centered override
+toolbar.addFlexChild(logo, { flexShrink: 0 });
+toolbar.addFlexChild(badge, { alignSelf: 'center' });
+
+// Background excluded from layout flow
+toolbar.addFlexChild(background, { flexExclude: true });
+```
 
+### Layout
+
+Higher-level layout with direction presets (`horizontal`/`vertical`/`grid`/`wrap`), viewport anchoring, and responsive breakpoints. Wraps FlexContainer.
+
+```typescript
 const toolbar = new Layout({
   direction: 'horizontal',
   gap: 20,
@@ -422,9 +466,109 @@ toolbar.updateViewport(width, height);
 
 **Anchors:** `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`
 
+### Button
+
+Per-state views with Tween animations. Each state accepts a `ViewInput` for full asset control:
+
+```typescript
+// Graphics-based (prototyping)
+const btn = new Button({
+  width: 200, height: 60, borderRadius: 12,
+  colors: { default: 0xffd700, hover: 0xffe44d, pressed: 0xccac00, disabled: 0x666666 },
+  text: 'SPIN',
+  onPress: () => spin(),
+});
+
+// Asset-based (production)
+const btn = new Button({
+  defaultView: 'btn-idle',       // texture name
+  hoverView: 'btn-hover',
+  pressedView: 'btn-pressed',
+  disabledView: 'btn-disabled',
+  text: 'SPIN',
+  onPress: () => spin(),
+});
+
+// NineSlice button
+const btn = new Button({
+  defaultView: new NineSliceSprite({ texture: Texture.from('btn-9s'), leftWidth: 20, topHeight: 20, rightWidth: 20, bottomHeight: 20 }),
+  text: 'BET MAX',
+});
+```
+
+### ProgressBar
+
+Animated fill bar with optional custom track/fill views:
+
+```typescript
+// Graphics-based
+const bar = new ProgressBar({ width: 400, height: 20, fillColor: 0x00ff00, animated: true });
+bar.progress = 0.75;
+bar.update(dt);
+
+// Asset-based
+const bar = new ProgressBar({
+  width: 400, height: 20,
+  trackView: 'bar-track',                       // texture name
+  fillView: new NineSliceSprite({ ... }),        // or any Container
+});
+```
+
+### Slider
+
+Draggable slider with customizable track, fill, and handle views:
+
+```typescript
+// Graphics-based
+const volume = new Slider({
+  min: 0, max: 1, value: 0.5, step: 0.1,
+  width: 200, height: 8,
+  fillColor: 0xffd700,
+  onUpdate: (v) => audio.setVolume('music', v),
+  onChange: (v) => console.log('Final:', v),
+});
+
+// Asset-based
+const volume = new Slider({
+  min: 0, max: 1, value: 0.5,
+  width: 200, height: 8,
+  trackView: 'slider-track',
+  fillView: 'slider-fill',
+  handleView: 'slider-handle',
+  onUpdate: (v) => audio.setVolume('music', v),
+});
+```
+
+`onUpdate` fires continuously during drag, `onChange` fires once when drag ends.
+
+### Toggle
+
+Two-state toggle switch with animation:
+
+```typescript
+// Graphics-based
+const mute = new Toggle({
+  value: false,
+  width: 52, height: 28,
+  onColor: 0x22cc22, offColor: 0x666666,
+  onChange: (on) => audio.muteAll(!on),
+});
+
+// Asset-based (custom ON/OFF views with crossfade)
+const ante = new Toggle({
+  value: false,
+  onView: 'toggle-on',
+  offView: 'toggle-off',
+  onChange: (on) => setAnteBet(on),
+});
+
+// Programmatic control
+mute.forceSwitch(true);
+```
+
 ### ScrollContainer
 
-Touch/drag scrollable container with mouse wheel, inertia, and dynamic rendering. Extends `@pixi/ui` ScrollBox.
+Touch/drag scrolling with mouse wheel, inertia, and optional visual scrollbar:
 
 ```typescript
 const scroll = new ScrollContainer({
@@ -432,66 +576,60 @@ const scroll = new ScrollContainer({
   direction: 'vertical',
   elementsMargin: 8,
   backgroundColor: 0x1a1a2e,
+  scrollbar: true,                    // show scrollbar indicator
+  scrollbarColor: 0xaaaaaa,           // or provide custom view:
+  // thumbView: 'scrollbar-thumb',    // texture name, Texture, or Container
 });
 for (let i = 0; i < 50; i++) scroll.addItem(createRow(i));
 ```
 
-### Button
+### Panel
 
-Extends `@pixi/ui` FancyButton. Supports Graphics-based and texture-based states, press animation, and text.
+Background panel with FlexContainer content layout. Supports Graphics or 9-slice backgrounds:
 
 ```typescript
-const spinBtn = new Button({
-  width: 200, height: 60,
-  borderRadius: 12,
-  colors: { default: 0xffd700, hover: 0xffe44d, pressed: 0xccac00, disabled: 0x666666 },
-  pressScale: 0.95,
-  text: 'SPIN',
+// Graphics background
+const panel = new Panel({ width: 600, height: 400, backgroundColor: 0x1a1a2e, borderRadius: 16, padding: 16 });
+panel.addContent(myLabel);
+
+// 9-slice texture background
+const panel = new Panel({
+  nineSliceTexture: 'panel-bg',
+  nineSliceBorders: [20, 20, 20, 20],
+  width: 600, height: 400, padding: 16,
 });
-spinBtn.onPress.connect(() => console.log('Spin!'));
-spinBtn.disable();
-spinBtn.enable();
 ```
 
 ### Other UI Components
 
-**Label** — styled text wrapper:
-```typescript
-new Label({ text: 'TOTAL WIN', style: { fontSize: 36, fill: 0xffffff } });
-```
-
-**BalanceDisplay** — animated currency display:
-```typescript
-const balance = new BalanceDisplay({ currency: 'USD', animated: true });
-balance.setValue(9500);
-```
-
-**WinDisplay** — countup win animation:
+**Label** — styled text with auto-fit and currency formatting:
 ```typescript
-await winDisplay.showWin(5000); // countup over 2 seconds
+const label = new Label({ text: 'TOTAL WIN', style: { fontSize: 36, fill: 0xffffff }, maxWidth: 300, autoFit: true });
+label.setCurrency(1500, 'USD'); // → "$1,500.00"
 ```
 
-**ProgressBar** — animated fill bar (wraps `@pixi/ui`):
+**BalanceDisplay** — animated currency countup/countdown:
 ```typescript
-const bar = new ProgressBar({ width: 400, height: 20, fillColor: 0x00ff00, animated: true });
-bar.progress = 0.75;
-bar.update(dt); // call each frame for animation
+const balance = new BalanceDisplay({ prefix: 'BALANCE', currency: 'USD', animated: true });
+balance.setValue(9500); // smooth countup
 ```
 
-**Panel** — background panel with flex layout (Graphics or 9-slice):
+**WinDisplay** — dramatic countup with scale pop:
 ```typescript
-const panel = new Panel({ width: 600, height: 400, backgroundColor: 0x1a1a2e, borderRadius: 16, padding: 16 });
-panel.content.addChild(myText); // children participate in flexbox
+await winDisplay.showWin(5000);
+winDisplay.hide();
 ```
 
-**Modal** — full-screen overlay dialog:
+**Modal** — full-screen overlay with enter/exit animations:
 ```typescript
 const modal = new Modal({ overlayAlpha: 0.7, closeOnOverlay: true, animationDuration: 300 });
+modal.content.addChild(settingsPanel);
 await modal.show(viewWidth, viewHeight);
 ```
 
-**Toast** — notification messages (`info`, `success`, `warning`, `error`):
+**Toast** — transient notifications with optional custom background:
 ```typescript
+const toast = new Toast({ duration: 3000, backgroundView: 'toast-bg' });
 await toast.show('Free spins activated!', 'success', viewWidth, viewHeight);
 ```
 
@@ -533,7 +671,7 @@ export default defineGameConfig({
 });
 ```
 
-**What `defineGameConfig` provides:** ESNext build target (for yoga-layout WASM), asset inlining (<8KB), PixiJS chunk splitting, DevBridge auto-injection in dev mode, dependency deduplication (`pixi.js`, `@pixi/layout`, `react`, etc.), and pre-bundling optimization.
+**What `defineGameConfig` provides:** ESNext build target, asset inlining (<8KB), PixiJS chunk splitting, DevBridge auto-injection in dev mode, dependency deduplication (`pixi.js`, `react`, etc.), and pre-bundling optimization.
 
 ---
 
@@ -686,42 +824,102 @@ bridge.destroy();
 
 ## React Integration
 
-Built-in React reconciler for PixiJS. No `@pixi/react` needed — renders React trees directly into PixiJS Containers.
+Built-in React reconciler for PixiJS. No `@pixi/react` needed — renders React trees directly into PixiJS Containers. All engine UI components work declaratively in JSX with full TypeScript autocompletion.
 
-```tsx
-import { ReactScene, extendPixiElements, useSDK, useViewport, useBalance } from '@energy8platform/game-engine/react';
+### Setup
 
-extendPixiElements(); // register PixiJS elements for JSX (call once)
+```typescript
+import { extendPixiElements, extendUIElements } from '@energy8platform/game-engine/react';
+
+extendPixiElements();  // Container, Sprite, Text, Graphics, etc.
+extendUIElements();    // Button, Label, FlexContainer, Panel, etc.
+```
+
+### ReactScene
+
+```tsx
+import { ReactScene, useEngine, useBalance } from '@energy8platform/game-engine/react';
+import { useState } from 'react';
 
-export class GameScene extends ReactScene {
-  render() { return <GameRoot />; }
+export class SlotScene extends ReactScene {
+  render() { return <SlotUI />; }
 }
 
-function GameRoot() {
-  const { width, height } = useViewport();
+function SlotUI() {
+  const { screen } = useEngine();
   const balance = useBalance();
-  const sdk = useSDK();
+  const [bet, setBet] = useState(1);
 
   return (
-    <container>
-      <text text={`Balance: $${balance.toFixed(2)}`} style={{ fontSize: 32, fill: 0xffffff }} />
-      <text text="SPIN" style={{ fontSize: 48, fill: 0xffd700 }}
-        eventMode="static" cursor="pointer"
-        onClick={async () => {
-          const result = await sdk?.play({ action: 'spin', bet: 1 });
-          sdk?.playAck(result!);
-        }}
-      />
-    </container>
+    <flexContainer direction="column" width={screen.width} height={screen.height} padding={20}>
+      {/* Top bar */}
+      <flexContainer direction="row" justifyContent="space-between" alignItems="center">
+        <balanceDisplay currency="USD" animated value={balance} />
+        <label text={`BET: $${bet.toFixed(2)}`} style-fontSize={18} style-fill={0xcccccc} />
+      </flexContainer>
+
+      {/* Controls */}
+      <flexContainer direction="row" justifyContent="center" gap={12} alignItems="center">
+        <button width={50} height={50} borderRadius={25} text="-"
+                colors-default={0x444444}
+                onPress={() => setBet(b => Math.max(0.2, b - 0.5))} />
+        <button width={140} height={60} borderRadius={30} text="SPIN"
+                colors-default={0x22aa44} colors-hover={0x33cc55}
+                onPress={() => { /* spin */ }} />
+        <button width={50} height={50} borderRadius={25} text="+"
+                colors-default={0x444444}
+                onPress={() => setBet(b => b + 0.5)} />
+      </flexContainer>
+    </flexContainer>
   );
 }
 ```
 
+### Declarative UI Components
+
+All engine UI components are config-based: the reconciler passes JSX props as a config object to the constructor, and calls `updateConfig()` on prop changes. Children of `<flexContainer>`, `<panel>`, and `<scrollContainer>` automatically participate in their layout system.
+
+```tsx
+{/* Asset-skinned button */}
+<button defaultView="btn-idle" hoverView="btn-hover" text="SPIN" onPress={handler} />
+
+{/* Panel with 9-slice background */}
+<panel nineSliceTexture="panel-bg" nineSliceBorders={[20,20,20,20]} width={400} height={300}>
+  <label text="Settings" style-fontSize={24} />
+</panel>
+
+{/* Progress bar with custom track/fill */}
+<progressBar trackView="bar-track" fillView="bar-fill" progress={0.75} width={300} height={20} />
+
+{/* Scrollable list */}
+<scrollContainer width={500} height={400} direction="vertical" scrollbar elementsMargin={8}>
+  <label text="Item 1" />
+  <label text="Item 2" />
+</scrollContainer>
+
+{/* Slider */}
+<slider min={0} max={1} value={volume} width={200} height={8}
+        fillColor={0xffd700} onUpdate={setVolume} />
+
+{/* Toggle */}
+<toggle value={isMuted} onColor={0x22cc22} onChange={setIsMuted} />
+
+{/* Flex item props — work on any element inside <flexContainer> */}
+<flexContainer direction="row" width={800} height={60}>
+  <graphics draw={drawBg} flexExclude />       {/* excluded from flow */}
+  <label text="Logo" flexShrink={0} />          {/* won't shrink */}
+  <container flexGrow={1} />                     {/* fills remaining space */}
+  <button text="Menu" alignSelf="center" />      {/* centered on cross-axis */}
+</flexContainer>
+```
+
+**Dash-notation** for nested config: `colors-default={0xff0000}` → `{ colors: { default: 0xff0000 } }`, `style-fontSize={24}` → `{ style: { fontSize: 24 } }`.
+
 ### Hooks
 
 | Hook | Returns | Description |
 | --- | --- | --- |
-| `useEngine()` | `EngineContextValue` | Full engine context |
+| `useEngine()` | `EngineContextValue` | Full engine context (app, sdk, audio, screen, etc.) |
 | `useSDK()` | `CasinoGameSDK \| null` | SDK instance |
 | `useAudio()` | `AudioManager` | Audio manager |
 | `useInput()` | `InputManager` | Input manager |
@@ -733,18 +931,18 @@ function GameRoot() {
 ### Element Registration
 
 ```typescript
-import { extendPixiElements, extendLayoutElements, extend } from '@energy8platform/game-engine/react';
+import { extendPixiElements, extendUIElements, extendCustomElements } from '@energy8platform/game-engine/react';
 
-extendPixiElements();                              // Container, Sprite, Text, Graphics, etc.
-extendLayoutElements(await import('@pixi/layout/components')); // @pixi/layout (if installed)
-extend({ Button, Panel });                         // custom classes
+extendPixiElements();                // Container, Sprite, Text, Graphics, AnimatedSprite, etc.
+extendUIElements();                  // Button, Label, FlexContainer, Panel, ProgressBar, etc.
+extendCustomElements({ MyWidget });  // your own classes
 ```
 
-After registration, use as lowercase JSX: `<container>`, `<sprite>`, `<text>`, `<graphics>`, `<button>`.
+After registration, use as lowercase JSX: `<container>`, `<sprite>`, `<text>`, `<graphics>`, `<button>`, `<flexContainer>`, `<panel>`, etc.
 
-**Props:** Regular props set directly (`alpha`, `visible`, `scale`). Nested via dash: `position-x`, `scale-y`. Events: `onClick` → `onclick`, `onPointerDown` → `onpointerdown`.
+**Props:** Regular props set directly (`alpha`, `visible`, `scale`). Nested via dash: `position-x`, `scale-y`, `colors-default`. Events: `onClick`, `onPointerDown`, `onPress` (Button).
 
-> React is entirely optional. Imperative (`Scene`) and React (`ReactScene`) scenes can coexist.
+> React is entirely optional. Imperative (`Scene`) and React (`ReactScene`) scenes can coexist in the same game.
 
 ---