GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

chore: share game-studio hermes plugin

Browse Source
This commit is contained in:
kdletters
2026-05-11 12:00:45 +08:00
parent d23cf3807d
commit 81f57ea5ce
43 changed files with 2230 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
.hermes/plugins/game-studio/skills/game-playtest/SKILL.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: game-playtest
description: Run browser-game playtests and frontend QA. Use when the user asks for smoke tests, screenshot-based verification, browser automation, HUD or overlay review, or structured issue-finding in a browser game.
---
# Game Playtest
## Overview
Use this skill to test browser games the way players experience them: through boot, input, scene transitions, HUD readability, and visual state changes. Prefer browser automation and screenshot review when the project supports it.
## Preferred Workflow
1. Boot the game and confirm the first actionable screen.
2. Exercise the main verbs.
3. Capture screenshots from representative states.
4. Check the UI layer independently from the render layer.
5. Report findings in severity order with reproduction steps.
## Tooling Guidance
- Prefer Playwright or equivalent browser automation already available in the repo.
- When the game is canvas or WebGL heavy, screenshots are mandatory because DOM assertions alone miss visual regressions.
- Use screenshots to judge playfield obstruction and HUD weight, not just correctness of text or layout.
- When deterministic automation is not practical, do a structured manual pass and capture evidence.
- For 3D rendering bugs or unexplained frame cost, use SpectorJS and browser performance tooling rather than guessing from code alone.
## Common Checks
### 2D checks
- sprite alignment and baseline consistency
- hit or hurt animation readability
- HUD overlap with the playfield
- command menu state changes
- tile or platform readability
- input-state feedback and turn-state clarity
### 3D checks
- first-load playability versus dashboard-like chrome
- persistent overlay weight versus playfield visibility
- camera control and camera reset behavior
- pointer-lock or drag-look transitions when menus and overlays open
- depth readability and silhouette clarity
- secondary panels collapsed or dismissible during normal play
- resize behavior
- WebGL context loss or renderer fallback behavior
- material or lighting regressions
- GLB or texture streaming stalls
- collision proxy or physics mismatch
- performance cliffs tied to post-processing or asset load
## Responsive and Browser Checks
- desktop and mobile viewport sanity
- safe-area and notch issues where relevant
- reduced-motion behavior for UI transitions
- keyboard, pointer, and pause-state handling
- React state and scene state synchronization when the project uses React Three Fiber
## Reporting Standard
Lead with findings. Keep each finding concrete:
- what the user sees
- how to reproduce it
- why it matters
- what likely subsystem owns it
## References
- Shared architecture: `../web-game-foundations/SKILL.md`
- Frontend review cues: `../game-ui-frontend/SKILL.md`
- 3D debugging notes: `../../references/webgl-debugging-and-performance.md`
- Full checklist: `../../references/playtest-checklist.md`

4
.hermes/plugins/game-studio/skills/game-playtest/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Game Playtest"
short_description: "Run browser-game playtests and QA"
default_prompt: "Playtest the browser game, check core interactions and visual state changes, and report concrete issues."

94
.hermes/plugins/game-studio/skills/game-studio/SKILL.md Normal file
View File

@@ -0,0 +1,94 @@
---
name: game-studio
description: Route early browser-game work. Use when the user needs stack selection and workflow planning across design, implementation, assets, and playtesting before moving to a specialist skill.
---
# Game Studio
## Overview
Use this skill as the umbrella entrypoint for browser-game work. Default to a 2D Phaser path unless the user explicitly asks for 3D, Three.js, React Three Fiber, shader-heavy rendering, or another WebGL-first direction.
This plugin is intentionally asymmetric:
- 2D is the strongest execution path in v1.
- 3D has one opinionated default ecosystem: vanilla Three.js for plain TypeScript or Vite apps, React Three Fiber for React-hosted 3D apps, and GLB or glTF 2.0 as the default shipping asset format.
- Shared architecture, UI, and playtest practices apply to both.
## Use This Skill When
- the user is still choosing a stack
- the request spans multiple domains such as runtime, UI, asset pipeline, and QA
- the user says "help me build a game" without naming the implementation path
## Do Not Stay Here When
- the runtime is clearly plain Three.js
- the runtime is clearly React Three Fiber
- the task is clearly a shipped-asset problem
- the task is clearly frontend-only or QA-only
Once the intent is clear, route to the most specific specialist skill and continue from there.
## Routing Rules
1. Classify the request before designing or coding:
- `2D default`: Phaser, sprites, tilemaps, top-down, side-view, grid tactics, action platformers.
- `3D + plain TS/Vite`: imperative scene control, engine-like loops, non-React apps, direct Three.js work.
- `3D + React`: React-hosted product surfaces, declarative scene composition, shared React state, UI-heavy 3D apps.
- `3D asset pipeline`: GLB, glTF, texture packaging, compression, LOD, runtime asset size.
- `Alternative engine`: Babylon.js or PlayCanvas requests, usually as comparison or ecosystem fit questions.
- `Shared`: core loop design, frontend direction, save/debug/perf boundaries, browser QA.
2. Route to the specialist skills immediately after classification:
- Shared architecture and engine choice: `../web-game-foundations/SKILL.md`
- Deep 2D implementation: `../phaser-2d-game/SKILL.md`
- Vanilla Three.js implementation: `../three-webgl-game/SKILL.md`
- React-hosted 3D implementation: `../react-three-fiber-game/SKILL.md`
- 3D asset shipping and optimization: `../web-3d-asset-pipeline/SKILL.md`
- HUD and menu direction: `../game-ui-frontend/SKILL.md`
- 2D sprite generation and normalization: `../sprite-pipeline/SKILL.md`
- Browser QA and visual review: `../game-playtest/SKILL.md`
3. Keep one coherent plan across the routed skills. Do not let engine, UI, asset, and QA decisions drift apart.
## Default Workflow
1. Lock the game fantasy and player verbs.
2. Define the core loop, failure states, progression, and target play session length.
3. Choose the implementation track:
- Default to Phaser for 2D browser games.
- Choose vanilla Three.js when the project is explicitly 3D and wants direct render-loop control in a plain TypeScript or Vite app.
- Choose React Three Fiber when the project already lives in React or wants declarative scene composition with shared React state.
- Choose raw WebGL only when the user explicitly wants a custom renderer or shader-first surface.
4. Define the UI surface early. Browser games usually need a DOM HUD and menu layer even when the playfield is canvas or WebGL.
- For 3D starter scaffolds, default to a low-chrome HUD that preserves the playfield and keeps secondary panels collapsed.
5. Decide the asset workflow:
- 2D characters and effects: use `sprite-pipeline`.
- 3D models, textures, and shipping format: use `web-3d-asset-pipeline`.
6. Close with a playtest loop before calling the work production-ready.
## Output Expectations
- For planning requests, return a game-specific plan with stack choice, gameplay loop, UI surface, asset workflow, and test approach.
- For implementation requests, keep the chosen stack obvious in the file structure and code boundaries.
- For mixed requests, preserve the plugin default: 2D Phaser first unless the user asks for something else.
- When the user asks about Babylon.js or PlayCanvas, compare them honestly but keep Three.js and R3F as the primary code-generation defaults unless the user explicitly chooses another engine.
## References
- Engine selection: `../../references/engine-selection.md`
- Three.js stack: `../../references/threejs-stack.md`
- React Three Fiber stack: `../../references/react-three-fiber-stack.md`
- 3D asset pipeline: `../../references/web-3d-asset-pipeline.md`
- Vanilla Three.js starter: `../../references/threejs-vanilla-starter.md`
- React Three Fiber starter: `../../references/react-three-fiber-starter.md`
- Frontend prompting patterns: `../../references/frontend-prompts.md`
- Playtest checklist: `../../references/playtest-checklist.md`
## Examples
- "Help me prototype a browser tactics game."
- "I need a Phaser-based action game loop with a HUD and menus."
- "I want a Three.js exploration demo with WebGL lighting and browser-safe UI."
- "I want a React-based 3D configurator with React Three Fiber."
- "Optimize my GLB assets for the web and keep the file sizes under control."
- "Set up the asset workflow for consistent 2D sprite animations."

4
.hermes/plugins/game-studio/skills/game-studio/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Game Studio"
short_description: "Route browser-game work to the right path"
default_prompt: "Help me choose the right browser-game stack and workflow before implementation starts."

112
.hermes/plugins/game-studio/skills/game-ui-frontend/SKILL.md Normal file
View File

@@ -0,0 +1,112 @@
---
name: game-ui-frontend
description: Design UI surfaces for browser games. Use when the user asks for HUDs, menus, overlays, responsive layouts, or visual direction that must protect the playfield.
---
# Game UI Frontend
## Overview
Use this skill whenever the game needs a visible interface layer. The job is not to produce generic dashboard UI. The job is to produce a readable, thematic browser-game interface that supports the play experience.
Default assumption: build the game world in canvas or WebGL, and build text-heavy UI in DOM.
## Frontend Standards
1. Establish visual direction before coding.
- Genre and fantasy
- Material language
- Typography
- Palette
- Motion tone
2. Use CSS variables for the UI theme.
3. Build clear hierarchy.
- Critical combat or survival information first
- Secondary tools second
- Rarely used settings behind menus or drawers
4. Protect the playfield first, especially in 3D.
- The initial screen should feel playable within a few seconds.
- Default to one primary persistent HUD cluster and at most one small secondary cluster.
- Keep the center of the playfield clear during normal play.
- Keep the lower-middle playfield mostly clear during normal play.
- Put lore, field notes, quest details, and long control lists behind drawers, toggles, or pause surfaces.
- Prefer contextual prompts and transient hints over permanent boxed panels.
5. Keep overlays readable over motion.
- Use backing panels, edge treatment, contrast, and restrained blur where needed.
6. Design for both desktop and mobile from the start.
7. Design 3D UI around camera and input control boundaries.
- Pause or gate camera-control input when menus, dialogs, or pointer-driven UI are active.
- Keep pointer-lock, drag-to-look, and menu interaction states explicit.
## 3D Starter Defaults
For exploration, traversal, or third-person starter scaffolds, prefer this UI budget:
- one compact objective chip or status strip at the edge
- one transient controls hint or interaction prompt
- one optional collapsible secondary surface such as a journal, map, or quest log
Do not open every informational surface on first load. The scene should be readable before the user opens any deeper UI.
As a default implementation constraint for 3D browser games:
- no always-on full-width header plus multi-card body plus full-width footer layout
- no large center-screen or lower-middle overlays during normal movement
- no more than roughly 20-25% of the viewport covered by persistent HUD on desktop unless the user explicitly requests a denser layout
- on mobile, collapse to a narrow stack or contextual chips before covering the playfield with larger panels
## Prompting Rules
When asking the model to design or implement game UI, include:
- the game fantasy
- the camera or viewpoint
- the player verbs
- the HUD layers
- the camera or control mode when the game is 3D
- the tone of motion
- desktop and mobile expectations
- playfield protection and disclosure strategy
- explicit anti-patterns to avoid
Use `../../references/frontend-prompts.md` for concrete prompt shapes.
## Motion Rules
- Prefer a few meaningful transitions over constant micro-animation.
- Reserve strong motion for state change, reward, danger, and onboarding.
- Respect reduced-motion settings for non-essential animation.
- Keep 3D HUD motion from competing with camera motion.
## What Good Looks Like
- HUD elements are legible without flattening the scene.
- Menus feel native to the game world, not like a SaaS admin panel.
- Layout adapts cleanly across breakpoints.
- Pointer, keyboard, and game-state feedback are obvious.
- In 3D games, menu and HUD states do not fight camera control or pointer-lock.
- In 3D games, the first playable view keeps most of the viewport available for movement, aiming, and spatial reading.
- Persistent information density is low enough that screenshots still read as game scenes, not UI comps.
## Anti-Patterns
- Generic app dashboard layouts
- Flat placeholder styling with no theme
- Default font stacks without intent
- Dense overlays that obscure the playfield
- Large title cards or multi-paragraph notes sitting over a live playable scene
- Equal-weight boxed panels distributed around every edge of the viewport
- Controls, objectives, notes, and lore all expanded at once on first load
- Full-width top-and-bottom chrome with large always-on center or body panels in 3D play
- Excessive motion on every element
- Canvas-only UI when DOM would be clearer and cheaper
- Forcing HUD controls into the 3D scene when standard DOM would be clearer
- Letting camera input remain active under modals or inventory panels
## References
- Shared architecture: `../web-game-foundations/SKILL.md`
- Prompt recipes: `../../references/frontend-prompts.md`
- Low-chrome 3D layout patterns: `../../references/three-hud-layout-patterns.md`
- React-hosted 3D UI context: `../react-three-fiber-game/SKILL.md`
- Playtest review: `../../references/playtest-checklist.md`

4
.hermes/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Game UI Frontend"
short_description: "Design browser-game HUDs, menus, and overlays"
default_prompt: "Design a browser-game UI layer that supports the play experience without crowding the playfield."

88
.hermes/plugins/game-studio/skills/phaser-2d-game/SKILL.md Normal file
View File

@@ -0,0 +1,88 @@
---
name: phaser-2d-game
description: Implement 2D browser games with Phaser. Use when the user wants a Phaser, TypeScript, and Vite stack for scenes, gameplay systems, cameras, sprite animation, and DOM-overlay HUD patterns.
---
# Phaser 2D Game
## Overview
Use this skill for the main execution path in this plugin. Phaser is the default stack for 2D browser games here because it handles rendering, timing, sprites, cameras, and scene orchestration well without forcing gameplay rules into the framework.
Preferred stack:
- Phaser
- TypeScript
- Vite
- DOM-based HUD or menus layered over the game canvas
## Architecture
1. Keep gameplay state outside Phaser scenes.
- Systems own rules, turn order, movement, combat, inventory, objectives, and progression.
- Phaser scenes adapt system state into sprites, camera motion, animation playback, and effects.
2. Make scenes thin.
- Boot and asset preload
- Menu or shell scene
- Gameplay scene
- Optional overlay or debug scene
3. Keep renderer-facing objects disposable.
- Sprite containers, emitters, tweens, and camera rigs are view state, not source of truth.
4. Favor stable asset manifest keys over direct file-path references throughout gameplay code.
## Implementation Guidance
- Use one integration boundary where the scene reads simulation state and emits input actions back.
- Prefer deterministic system updates over scene-local mutation.
- Treat HUD and menus as DOM when text, status density, or responsiveness matter.
- Keep animation state derived from gameplay state rather than ad hoc sprite flags.
## 2D Modes Covered Well
- Turn-based grids and tactics
- Top-down exploration
- Side-view action platformers
- Character-action combat with sprite animation
- Lightweight management or deck-driven battle scenes
## Camera and Presentation
- Choose the camera model early: locked, follow, room-based, or tactical-pan.
- Keep camera logic separate from game rules.
- Use restrained screen shake, hit-stop, and parallax. Effects should improve readability, not obscure it.
## UI Integration
- Use DOM overlays for HUD, command menus, settings, and narrative panels.
- Keep the canvas responsible for the world, combat readability, and motion.
- Avoid shoving dense text or complex settings UIs into Phaser unless the project explicitly needs an in-canvas presentation.
## Asset Organization
- `characters/`
- `environment/`
- `ui/`
- `fx/`
- `audio/`
- `data/`
Keep manifest keys human-readable and stable.
## Default Directory Shape
See `../../references/phaser-architecture.md` for a concrete module split.
## Anti-Patterns
- Game rules inside `update()` loops without a system boundary
- Scene-to-scene state passed through mutable global objects
- HUD text rendered in the game canvas just because it is convenient
- Asset paths embedded everywhere instead of a manifest layer
- Overusing generic React dashboard patterns for game UI
## References
- Shared architecture: `../web-game-foundations/SKILL.md`
- Frontend direction: `../game-ui-frontend/SKILL.md`
- Sprite workflow: `../sprite-pipeline/SKILL.md`
- Phaser structure: `../../references/phaser-architecture.md`

4
.hermes/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Phaser 2D Game"
short_description: "Build 2D browser games with Phaser"
default_prompt: "Implement this 2D browser game with Phaser, TypeScript, and a clear gameplay architecture."

87
.hermes/plugins/game-studio/skills/react-three-fiber-game/SKILL.md Normal file
View File

@@ -0,0 +1,87 @@
---
name: react-three-fiber-game
description: Build React-hosted 3D browser games with React Three Fiber. Use when the user wants pmndrs-based scene composition, shared React state, and 3D HUD integration inside a React app.
---
# React Three Fiber Game
## Overview
Use this skill when the 3D runtime lives inside a React application. This is the default React-native 3D path in the plugin and should be preferred over vanilla Three.js when the app shell, settings, storefront, editor surface, or surrounding product already uses React.
Recommended stack:
- `@react-three/fiber`
- `three`
- `@react-three/drei`
- `@react-three/rapier`
- `@react-three/postprocessing`
- `@react-three/a11y` when accessibility-sensitive interaction matters
- DOM overlays in the normal React tree
## Use This Skill When
- the project already uses React
- the 3D scene must share state with the rest of the app
- declarative scene composition is a net gain
- the team wants pmndrs helpers instead of building every helper layer by hand
## Do Not Use This Skill When
- the app is not React-based
- the project wants a cleaner imperative runtime with minimal React coordination
- the problem is asset packaging rather than runtime composition
## Best Fit Scenarios
- 3D configurators and tool-rich browser products
- React apps with embedded game or scene surfaces
- 3D menus, editors, or world maps in an existing React app
- 3D game UIs that depend on shared app state and non-canvas shells
## Core Rules
1. Keep simulation state outside render components.
- React components should describe scene composition, not become the source of truth for gameplay rules.
2. Use React state and scene state deliberately.
- Shared UI state can live in app state.
- High-frequency simulation should not force the whole app through unnecessary React churn.
3. Use pmndrs helpers intentionally.
- Drei for controls, loaders, helpers, environments, and common scene primitives.
- `@react-three/rapier` for physics integration.
- `@react-three/postprocessing` for optional effects.
- `@react-three/a11y` when the interaction model benefits from accessible scene semantics.
4. Keep HUD, settings, and menus in DOM by default.
5. Keep starter scaffolds visually restrained.
- Start with one compact objective or status surface and transient prompts.
- Keep notes, maps, and multi-step checklists collapsed until opened.
- Do not surround the `Canvas` with equally weighted glass cards.
## Architectural Guidance
- Use a dedicated scene root component that owns the `Canvas`.
- Keep camera rigs and control components isolated from gameplay systems.
- Keep loader and asset wrappers predictable.
- Keep DOM overlays and the 3D scene coordinated through explicit state boundaries.
- If a system needs tight imperative control, isolate it rather than forcing everything into declarative patterns.
- If the scene is immediately playable, keep the initial overlay budget low and let the world do more of the onboarding.
## Anti-Patterns
- Treating React components as the gameplay state store
- Pushing heavy per-frame mutation through broad app state
- Using R3F only because React is available, even when the project needs a cleaner imperative runtime
- Building HUD or inventory UI inside the 3D scene by default
- Shipping an initial scaffold with large cards occupying every side of the viewport
## References
- Shared architecture: `../web-game-foundations/SKILL.md`
- Frontend direction: `../game-ui-frontend/SKILL.md`
- 3D HUD layout patterns: `../../references/three-hud-layout-patterns.md`
- React Three Fiber stack: `../../references/react-three-fiber-stack.md`
- React starter: `../../references/react-three-fiber-starter.md`
- GLB loader starter: `../../references/gltf-loading-starter.md`
- Rapier starter: `../../references/rapier-integration-starter.md`
- 3D asset pipeline: `../../references/web-3d-asset-pipeline.md`
- WebGL debugging and perf: `../../references/webgl-debugging-and-performance.md`

4
.hermes/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "React Three Fiber Game"
short_description: "Build React-hosted 3D browser games"
default_prompt: "Build this 3D browser game with React Three Fiber and keep the 3D runtime aligned with the React app shell."

102
.hermes/plugins/game-studio/skills/sprite-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,102 @@
---
name: sprite-pipeline
description: Generate and normalize 2D sprite animations. Use when the user asks for full-strip generation from approved source frames, consistent anchor and scale normalization, or preview assets for browser-game animation.
---
# Sprite Pipeline
## Overview
Use this skill for 2D sprite generation and normalization. This workflow is intentionally anchored around one approved frame and a whole-strip generation pass because frame-by-frame generation drifts too easily.
This skill is 2D-specific. If the request is for 3D characters, meshes, or materials, route back through `../game-studio/SKILL.md`.
## Core Workflow
1. Start from an approved in-game seed frame.
- The seed frame should already reflect the right silhouette, palette, costume, and proportions.
2. Build a larger transparent reference canvas around that frame.
- Use `../../scripts/build_sprite_edit_canvas.py`.
3. Ask for the full animation strip in one edit request.
- Do not generate each frame independently unless the user explicitly accepts lower consistency.
4. Normalize the result into fixed-size game frames.
- Use `../../scripts/normalize_sprite_strip.py`.
- Use one shared scale across the whole strip.
- Align frames with one shared anchor, typically bottom-center.
5. Optionally lock frame 01 back to the shipped seed frame.
- Do this when the animation should begin from the exact idle or base pose already in game.
6. Render a preview sheet and inspect the animation in-engine before approving it.
- Use `../../scripts/render_sprite_preview_sheet.py`.
## Prompting Rules
Always preserve these invariants in the prompt:
- same character
- same facing direction
- same palette family
- same silhouette family
- same readable face or key features
- same outfit proportions
- transparent background
- exact frame count and slot layout
Always ask for:
- one strip at once
- a transparent canvas
- no scenery, labels, or poster composition
- crisp pixel-art clusters for pixel work
- production asset tone, not concept art
## Using Image Generation
For live asset generation or edits, use the installed `imagegen` skill in this workspace. This skill defines the game-specific process; `imagegen` handles the API-backed generation or edit execution.
## Script Recipes
Create a reference canvas:
```bash
python3 scripts/build_sprite_edit_canvas.py \
--seed output/sprites/idle-01.png \
--out output/sprites/hurt-edit-canvas.png \
--frames 4 \
--slot-size 256 \
--canvas-size 1024
```
Normalize a raw strip:
```bash
python3 scripts/normalize_sprite_strip.py \
--input output/sprites/hurt-raw.png \
--out-dir output/sprites/hurt \
--frames 4 \
--frame-size 64 \
--anchor output/sprites/idle-01.png \
--lock-frame1
```
Render a preview sheet:
```bash
python3 scripts/render_sprite_preview_sheet.py \
--frames-dir output/sprites/hurt \
--out output/sprites/hurt-preview.png \
--columns 4
```
## Quality Gates
- proportions stay stable across frames
- frame-to-frame size does not drift
- action reads clearly at game scale
- transparency is preserved
- frame 01 matches the shipped sprite when lockback is enabled
- preview looks correct before any in-engine asset index update
## References
- Detailed workflow: `../../references/sprite-pipeline.md`
- Shared frontend context: `../game-ui-frontend/SKILL.md`

4
.hermes/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Sprite Pipeline"
short_description: "Generate and normalize 2D sprite animations"
default_prompt: "Create and normalize 2D sprite animation assets for a browser game with consistent scale and anchors."

124
.hermes/plugins/game-studio/skills/three-webgl-game/SKILL.md Normal file
View File

@@ -0,0 +1,124 @@
---
name: three-webgl-game
description: Implement browser-game runtimes with plain Three.js. Use when the user wants imperative scene control in TypeScript or Vite with GLB assets, loaders, physics, and low-level WebGL debugging.
---
# Three WebGL Game
## Overview
Use this skill for the default non-React 3D path in the plugin. This is not generic WebGL advice. It is an opinionated stack for browser 3D work:
- `three`
- TypeScript
- Vite
- GLB or glTF 2.0 assets
- Three.js loaders such as `GLTFLoader`, `DRACOLoader`, and `KTX2Loader`
- Rapier JS for physics
- SpectorJS for GPU and frame debugging
- DOM overlays for HUD, menus, and settings
Use this skill when the project wants direct scene, camera, renderer, and game-loop control. If the app already lives in React, route to `../react-three-fiber-game/SKILL.md` instead.
## Use This Skill When
- the app is plain TypeScript or Vite rather than React-first
- the project wants direct imperative control over the render loop
- the user asks for Three.js specifically
- the runtime needs engine-like control over scene, camera, loaders, and physics
## Do Not Use This Skill When
- the 3D scene lives inside an existing React app
- the main problem is shipped-asset optimization rather than runtime code
- the user explicitly chose Babylon.js or PlayCanvas
## Core Rules
1. Keep simulation state outside Three.js objects.
- Game rules, AI, quest state, timers, and progression should not live inside meshes or materials.
2. Treat the render graph as an adapter.
- Scene graph, cameras, materials, loaders, and post-processing are view concerns layered over simulation state.
3. Keep camera behavior explicit.
- Orbit, follow, chase, rail, and first-person styles each need their own control boundary.
4. Keep UI out of WebGL unless the presentation absolutely depends on it.
- Menus, HUD, inventories, and settings should default to DOM.
5. Use GLB or glTF 2.0 as the default shipping model format.
- Do not build the runtime around DCC-native formats.
6. Use Rapier instead of ad hoc collision code when the game has meaningful 3D physics or collision response.
7. Keep the first playable view low-chrome.
- Default to one compact objective or status cluster plus transient prompts.
- Long notes, lore, and controls references should be collapsed until asked for.
- Do not frame the scene with multiple equal-weight cards during normal play.
## Initial Scaffold UX
For exploration, traversal, and character-control prototypes, start with a sparse shell:
- one edge-aligned objective chip
- one transient controls hint
- one optional compact status strip
Only add larger UI surfaces when the game loop truly requires them. Journal, quest log, codex, map, and settings surfaces should open on demand, not occupy the viewport by default.
## Recommended Structure
Use the module shape in `../../references/three-webgl-architecture.md`, then keep these boundaries clean:
- `simulation/`: rules, progression, state, and AI
- `render/app/`: renderer, scene, camera, resize, context lifecycle
- `render/loaders/`: GLTF, Draco, KTX2, texture, and environment loading
- `render/objects/`: mesh instantiation and disposal
- `render/materials/`: material setup and shader boundaries
- `physics/`: Rapier world, bodies, colliders, and simulation bridge
- `ui/`: DOM overlays and menus
- `diagnostics/`: debug toggles, perf probes, and capture hooks
## Good Fit Scenarios
- Exploration demos
- Lightweight 3D combat prototypes
- Vehicle or traversal prototypes
- Scene-driven product or world showcases with gameplay
- Material, lighting, or post-process-led experiences
- 3D games where camera movement and depth readability are central
## Loaders, Assets, and Post-Processing
- Start with `GLTFLoader` for shipped 3D content.
- Add `DRACOLoader` or Meshopt-compatible optimization as part of the asset pipeline, not as a random runtime patch.
- Use `KTX2Loader` for compressed textures when the asset pipeline provides them.
- Prefer built-in Three.js render and post-processing utilities first. Add heavier abstraction only when the project actually needs it.
- Keep post-processing optional and measurable. Bloom and color effects should not hide gameplay readability.
## Shader and Material Guidance
- Start with standard Three.js materials and correct lighting before reaching for custom shaders.
- Use custom shaders only when the visual target genuinely needs them.
- Keep shader parameters driven by game state, not by incidental scene mutations.
- If a material stack gets complex, isolate it behind material factories instead of scattering shader setup across scene code.
## Browser Safety
- Handle resize explicitly.
- Expect WebGL context loss and recovery.
- Keep a fallback or degraded mode in mind for fragile GPU paths.
- Watch texture size, geometry count, draw-call growth, and post-processing cost.
- Use SpectorJS when the scene behaves incorrectly or frame cost is unclear.
## Scope Warning
Do not claim that this plugin offers equal 3D depth to the Phaser track. It supports serious 3D implementation, but the plugin is still 2D-first overall.
## References
- Shared architecture: `../web-game-foundations/SKILL.md`
- Frontend direction: `../game-ui-frontend/SKILL.md`
- 3D HUD layout patterns: `../../references/three-hud-layout-patterns.md`
- Three.js ecosystem: `../../references/threejs-stack.md`
- Three.js structure: `../../references/three-webgl-architecture.md`
- Vanilla starter: `../../references/threejs-vanilla-starter.md`
- GLB loader starter: `../../references/gltf-loading-starter.md`
- Rapier starter: `../../references/rapier-integration-starter.md`
- 3D asset pipeline: `../../references/web-3d-asset-pipeline.md`
- WebGL debugging and perf: `../../references/webgl-debugging-and-performance.md`

4
.hermes/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Three WebGL Game"
short_description: "Build browser-game runtimes with Three.js"
default_prompt: "Implement this browser-game runtime with plain Three.js and keep the scene architecture easy to debug."

78
.hermes/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,78 @@
---
name: web-3d-asset-pipeline
description: Prepare and optimize browser-game 3D assets. Use when the user asks for GLB or glTF shipping work, including Blender cleanup and export, collision or LOD setup, compression, texture packaging, and runtime validation.
---
# Web 3D Asset Pipeline
## Overview
Use this skill for shipped 3D assets, not runtime scene code. The default output format for browser 3D work in this plugin is GLB or glTF 2.0. The goal is predictable runtime assets, not whatever the DCC tool happened to export first.
This guidance is engine-agnostic and can serve Three.js, React Three Fiber, Babylon.js, or PlayCanvas.
## Use This Skill When
- the task is about GLB or glTF shipping format
- the task is about model cleanup, texture packaging, compression, LOD, or collision proxies
- the runtime stack is already chosen and the remaining problem is asset quality or size
## Do Not Use This Skill When
- the task is about scene, camera, renderer, or game-loop structure
- the task is purely about React versus vanilla Three.js routing
- the user is still deciding between runtime engines
## Default Pipeline
1. Author and clean the source asset in a DCC tool such as Blender.
2. Export to GLB or glTF 2.0.
3. Optimize with glTF Transform.
4. Validate naming, pivots, transforms, material reuse, and texture budgets.
5. Add collision proxies, LOD strategy, and baked-lighting assumptions as needed.
6. Ship the optimized asset and load it with engine-native GLTF support.
## Format Rules
- Default shipping format: GLB or glTF 2.0.
- Do not treat FBX, OBJ, or DCC-native formats as the long-term runtime contract.
- Apply or normalize transforms before shipping.
- Keep units, pivots, and orientation conventions consistent across the whole asset set.
## Optimization Rules
- Use glTF Transform for pruning, deduplication, simplification, and packaging.
- Use geometry compression intentionally.
- Draco is a valid option when decode cost and compatibility fit the runtime.
- Meshopt is often a strong default for web delivery.
- Compress textures deliberately.
- Use KTX2 or BasisU when the runtime stack supports it.
- Use WebP or AVIF where they make sense in the broader asset pipeline.
- Reuse materials and textures where possible to cut memory and draw-call cost.
## Runtime-Ready Asset Rules
- Keep model hierarchy names stable and meaningful.
- Set pivots and origins for gameplay interaction, not just for DCC convenience.
- Author explicit collision proxies for physics-heavy scenes.
- Decide whether lighting is dynamic, baked, or hybrid before final export.
- Plan LODs for large environments or repeated props.
- Keep texture resolution proportional to on-screen use, not source-art ambition.
## Common Failure Modes
- Shipping raw DCC exports without cleanup
- Too many unique materials
- Texture sizes far above visible need
- Missing collision proxies
- Scale or pivot mismatches between assets
- Runtime code compensating for asset mistakes that should be fixed upstream
## References
- Three.js stack: `../../references/threejs-stack.md`
- React Three Fiber stack: `../../references/react-three-fiber-stack.md`
- GLB loader starter: `../../references/gltf-loading-starter.md`
- Rapier starter: `../../references/rapier-integration-starter.md`
- 3D asset pipeline reference: `../../references/web-3d-asset-pipeline.md`
- Alternative engines: `../../references/alternative-3d-engines.md`

4
.hermes/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Web 3D Asset Pipeline"
short_description: "Prepare and optimize browser-game 3D assets"
default_prompt: "Prepare these browser-game 3D assets for shipping as predictable runtime-ready GLB or glTF files."

95
.hermes/plugins/game-studio/skills/web-game-foundations/SKILL.md Normal file
View File

@@ -0,0 +1,95 @@
---
name: web-game-foundations
description: Set browser-game architecture before implementation. Use when the user needs engine choice, simulation and render boundaries, input model, asset organization, or save/debug/performance strategy.
---
# Web Game Foundations
## Overview
Use this skill to establish the non-negotiable architecture before implementation starts. Browser games degrade quickly when simulation, rendering, UI, asset loading, and input handling are mixed together.
Default rule: simulation state is owned outside the renderer, browser UI is not forced into the canvas unless there is a clear reason, and shipped 3D assets default to GLB or glTF 2.0 rather than ad hoc model formats.
## Use This Skill When
- the user has not settled the engine or renderer choice
- the task is about boundaries, module shape, state ownership, or asset policy
- multiple specialist skills need one shared architectural frame
## Do Not Stay Here When
- the runtime track is clearly Phaser
- the runtime track is clearly vanilla Three.js
- the runtime track is clearly React Three Fiber
- the task is purely about shipped 3D assets
Once the stack is clear, hand off to the runtime or asset specialist skill.
## Architecture Rules
1. Separate simulation from rendering.
- Simulation owns entities, turns, timers, collisions, progression, and saveable state.
- The renderer owns scene composition, animation playback, camera, particles, and input plumbing.
2. Keep input mapping explicit.
- Define actions such as `move`, `confirm`, `cancel`, `ability-1`, and `pause`.
- Map physical inputs to actions in one place.
3. Treat asset loading as a first-class system.
- Use stable manifest keys.
- Group by domain: characters, environment, UI, audio, FX.
- For 3D content, standardize on GLB or glTF 2.0 unless the chosen engine ecosystem requires another format upstream.
4. Define save/debug/perf boundaries up front.
- Save serializable simulation state, not renderer objects.
- Keep debug overlays and perf probes easy to toggle.
5. Use DOM overlays for menus and HUD by default.
- Canvas or WebGL should handle the playfield.
- DOM should handle text-heavy HUD, menus, settings, and accessibility-sensitive controls.
- In 3D, keep the persistent UI budget small so the scene stays readable and interactive.
6. Lock 3D runtime conventions early.
- Choose consistent units, origins, pivots, and naming conventions.
- Decide how collision proxies, LODs, and baked lighting data are authored before runtime integration starts.
## Engine Selection
- Default to Phaser for 2D games with sprites, tilemaps, top-down or side-view action, turn-based grids, and classic browser arcade flows.
- Default to vanilla Three.js for explicit 3D scenes that want direct scene, camera, renderer, and loop control in plain TypeScript or Vite.
- Default to React Three Fiber when the 3D scene lives inside a React application and needs declarative composition, shared app state, or React-first UI coordination.
- Use raw WebGL only for shader-heavy or renderer-first projects where engine abstractions would get in the way.
- Keep Babylon.js and PlayCanvas as alternative-engine paths rather than the default code-generation target.
See `../../references/engine-selection.md` for the default decision table.
## Implementation Checklist
Define these before writing core code:
- Player fantasy and primary verbs
- Core loop and loss or reset states
- Camera model
- Input action map
- Simulation modules
- Renderer modules
- Asset manifest layout
- 3D asset format and optimization rules
- HUD and menu surfaces
- Save data boundary
- Debug and perf surfaces
## Anti-Patterns
- Mixing gameplay rules directly into scene callbacks
- Treating the renderer as the source of truth for game state
- Putting all HUD and menu UI into the canvas by default
- Letting asset filenames become the public API instead of manifest keys
- Shipping unoptimized 3D assets straight from the DCC tool into the browser
- Mixing camera-control state and menu or modal state without an explicit input boundary
- Rebuilding architecture every time the game changes genre
## References
- Engine selection: `../../references/engine-selection.md`
- Phaser structure: `../../references/phaser-architecture.md`
- Three.js structure: `../../references/three-webgl-architecture.md`
- Three.js ecosystem stack: `../../references/threejs-stack.md`
- React Three Fiber stack: `../../references/react-three-fiber-stack.md`
- 3D asset shipping: `../../references/web-3d-asset-pipeline.md`

4
.hermes/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml Normal file
View File

@@ -0,0 +1,4 @@
interface:
display_name: "Web Game Foundations"
short_description: "Set browser-game architecture before implementation"
default_prompt: "Establish the core architecture for this browser game before implementation starts."