Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

web-game-runtime

/web-game-runtime

Tworzy szkielet i kod gier przeglądarkowych w three.js z WebGPU, Vite, stałym krokiem pętli i fizyką Rapier.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
32
Skrypty
18
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 18 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: assets/template/scripts/build-assets.ts, assets/template/scripts/generate-media.ts, assets/template/scripts/preview_glb.py, assets/template/scripts/release.ts, assets/template/src/engine/animation.ts, assets/template/src/engine/assets.ts, assets/template/src/engine/audio.ts, assets/template/src/engine/input.ts, assets/template/src/engine/levels.ts, assets/template/src/engine/loading.ts, assets/tem

Co robi i kiedy

Tworzy szkielet i kod gier przeglądarkowych w three.js z WebGPU, Vite, stałym krokiem pętli i fizyką Rapier.

Oryginalny opis (EN)

Scaffold and implement browser games with three.js WebGPURenderer (automatic WebGL2 fallback), Vite, a fixed-timestep loop, optional Rapier 3D/2D physics, GLB loading with collider tags, and a window.__game test-hook contract for headless playtesting. Use when starting a web game project or writing three.js/Rapier game code.

Jak działa

  1. Scaffold
  2. Engine modules (src/engine/)
  3. The window.game contract (the playtests rely on it)
  4. Rules for game code
  5. TypeScript
  6. References (read when relevant)
Sekcje z nagłówków SKILL.md, w oryginale · 93 linii, 1 709 słów
Podgląd SKILL.md
---
name: web-game-runtime
description: Scaffold and implement browser games with three.js WebGPURenderer (automatic WebGL2 fallback), Vite, a fixed-timestep loop, optional Rapier 3D/2D physics, GLB loading with collider tags, and a window.__game test-hook contract for headless playtesting. Use when starting a web game project or writing three.js/Rapier game code.
---

# web-game-runtime

## Scaffold
```bash
node <skill>/scripts/scaffold.ts . --lab-bpy <blender-assets skill>/scripts/lab_bpy.py   # never overwrites existing files
pnpm install
```
The scaffold copies `index.html`, `vite.config.ts`, `tsconfig.json`, `src/engine/*`, `design/style.json`, `tests/` and a `.gitignore`. Use the script rather than `cp -r`: agents' permission systems usually block recursive copies. Scripts:
- `pnpm dev`: development server
- `pnpm typecheck`: strict TypeScript check (`tsc`, no emit); `pnpm build` runs it first
- `pnpm build`, then `pnpm preview`: production build and preview
- `pnpm assets`: Blender → GLB
- `pnpm media`: AI images, sound effects and music from `design/media.json` (the `generate-media` skill)
- `pnpm release`: optimized HTML5 build in `dist/` (minify, meshopt GLBs, budgets). Deploying is the `publish-web-game` skill.

`vite.config.ts` is publish-ready: relative `base: './'`, three.js in its own chunk, and `vite-plugin-wasm` for Rapier's real `.wasm` (`@dimforge/rapier3d`, loaded lazily). Keep these settings.

Before you write any game code, check the starter scene boots on both backends with the `game-judge` playtest.

## Engine modules (`src/engine/`)
| module | provides |
|---|---|
| `renderer.ts` | `createRenderer()` → `{ renderer, backend }`; `?renderer=webgl2` forces fallback; `TEST_MODE` (`?test`), `params` |
| `loop.ts` | `createLoop({ update, render, renderer, hz })` fixed step (always pass `renderer`); auto-runs unless `?test`; `step(n)` for tests; frame stats |
| `physics.ts` | `createPhysics({ gravity, hz, substeps })` → `{ RAPIER, world, step, sync, bind, onSensor, collidersFromGltf }` |
| `assets.ts` | `loadModels(names, onProgress)`: all GLBs fetched **in parallel** with byte progress (uses `asset-manifest.json` in release builds), meshopt-aware; `await loadModel(name)` returns a clone (rigged models: own skeleton, clips in `userData.animations`); for many instances, `preloadModels([name], p)` in the download phase, then clone |
| `animation.ts` | `createAnimator(model)` → `play(name, { loop, timeScale })` (cross-fades; repeat calls are no-ops), `scrub(name, u)` (hold a clip at 0..1 of its length, driven by game state: a pendulum's angle), `update(dt)` **in the fixed-step `update`**, `current`, `counts` (for `getState()`) |
| `style.ts` | `style` (design/style.json), `applyStyle(scene, renderer)` → `{ sun, hemi, refreshShadows, setTheme }` (background, fog, hemi + sun w/ shadows, tone mapping), `paletteColor(role)`; per-level looks: `"themes": { name: partial style }` in style.json, `setTheme(name)` (uniforms only, no recompiles), `themeStyle(name)` |
| `input.ts` | `createInput(canvas)` → held `keys`, pointer `drag`, `on('dragstart' \| 'dragend', fn)` (`pointercancel` ends a drag as `{dx:0, dy:0, cancelled}`) |
| `audio.ts` | `createAudio({ volume, musicVolume })` → `load(names, onProgress)` (`public/sfx/<name>.mp3`, parallel, decoded up front), `play(name, { volume, rate })`, `setMuted` (music too), `counts` (plays per sound, also in `?test` where nothing is audible); music: `loadMusic(names, p)` (`public/music/<name>.mp3` + loop `.json`), `playMusic(name, { volume })` (seamless loop, cross-fades, waits for the first gesture), `stopMusic()`, `music` (current name, for `getState()`), `trackInfo(name)` (bpm, loop) |
| `loading.ts` | `createLoadingScreen({ title, image })` → `parallel(label, [{ weight, run(progress) }])`, `step(label, weight, fn(progress))`, `done()`; `prewarm(renderer, scene, camera, roots, onProgress)`; `compileInBackground(renderer, scene, camera, root)` (off-screen, during play) |
| `levels.ts` | level streaming: `createLevels([{ models, sfx, music }], { audio })` → `download(i, p)`, `attach(renderer, scene, camera)`, `prewarm(i, p)` (behind the loading screen), `load(i, p)` (download + background compile), `prefetch(i)`, `isReady(i)`, `models(i)`, `statuses()` |
| `testHooks.ts` | `installTestHooks({ backend, loop, getState, input })`, `createRng(seed)` |

Boot order in `main.ts`:
1. `createLoadingScreen()`; it is shown first
2. **One parallel download phase:** `loading.parallel('Loading…', [createRenderer, createPhysics, loadModels(SHARED_MODELS, p), audio.load(SFX, p), levels.download(first, p), …])`. Every download (models, Rapier `.wasm`, audio, textures) starts at once. Never `await` one download before starting the next. Shared assets plus **only the first level**; with a single level, load everything here.
3. scene and camera, then `applyStyle` (lights must exist before prewarm), `levels.attach(renderer, scene, camera)`
4. build game objects from the loaded models
5. **prewarm** the shared objects and the first level (`loading.step('Compiling shaders', …, p => levels.prewarm(first, p))`, or `prewarm(..., roots, p)`)
6. build the first level (`collidersFromGltf`), `levels.prefetch(first + 1)`, then `installTestHooks`
7. `createLoop({ update, render, renderer })`, `loop.start()`, `loop.step(0)`, `loading.done()`, then `hooks.ready = true`

**Every game must have the loading screen and prewarm.** Lazy shader/pipeline compilation causes hitches the first time a level, effect or material appears.

**Multi-level games stream levels** (`levels.ts`, example: `examples/minigolf`): list each level's GLBs, sfx and music in `design/levels.json` (`{ "levels": [{ "models": [], "music": [], ...game fields }] }`, imported by `main.ts`). Play starts once level 1 is ready. Whenever a level starts, `prefetch` the next one: it downloads and compiles off-screen while the player plays. On a level change, swap in instantly if `isReady(i)`; otherwise show a small "Loading…" card (`load(i, p)`), keep the old level on screen, and swap in `update()` once it is ready. Expose `levels: levels.statuses()` in `getState()`. Bots must `await` (e.g. 50 ms) while the game is loading; a synchronous `step` loop starves the download. `pnpm release` reads `design/levels.json` and doesn't add preload hints for later-level assets.

## The `window.__game` contract (the playtests rely on it)
- `ready` is set after the first frame renders. `backend` is `'webgpu'` or `'webgl2'`.
- `step(n)` advances exactly n fixed ticks and renders once. With `?test` nothing advances unless asked, so runs are deterministic.
- `getState()` returns plain JSON: phase, score, level, player position and speed, and anything else a rule depends on.
- `input(action)` takes the **same** action objects the real controls produce. Add test helpers too: `loadLevel`, `reset`, `camera: 'overview'`.
- `stats()` returns realtime frame stats (`?test&realtime`).

## Rules for game code
- Gameplay state changes happen only in `update(dt)`. `render()` syncs meshes and draws.
- Use `createRng()` for randomness. Never use `Date.now()` or `performance.now()` in gameplay.
- Load levels from GLB plus named marker empties (Spawn, Goal…). Read them with `root.getObjectByName('Spawn').getWorldPosition(v)`.
- To change level, call `physics.removeBody(levelBody)`; it removes the colliders and sensor handlers too. Remove the old scene root, add the new one, `setTheme()` if levels have their own look, then call `refreshShadows()` (from `applyStyle`). Every level must be compiled before it is shown: the first by `prewarm`, the rest by `levels.load`/`prefetch`.
- Support a `?level=N` deep link (read with `params` from `renderer.ts`), so people reviewing the game can jump straight to a level.
- Controls: read a drag in the frame captured on `dragstart`, never against a camera that the drag itself moves (that is a feedback loop, and the view spins). Hold the camera still during the gesture. Add a dead zone. Test with **real** held `drag`/`key` playtest steps, not only `input()` actions. See `references/controls.md`.
- After any change the user can see or feel, end with a checked `pnpm dev` link, the controls and what to try (the `make-web-game` skill's hand-off rule). Don't make the user ask where to test.
- Use a DOM overlay (`#hud`) for the HUD; it is cheap and readable in screenshots. Show the controls on screen. Time HUD flashes in game ticks, not `setTimeout`, or stepped screenshots catch them half-faded; hide them under end cards.
- No physics needed (grid or circle collisions, a pendulum)? Run the boot playtest first (the starter scene uses physics), then delete `src/engine/physics.ts` and the `@dimforge/rapier3d` dependency. Keep `vite.config.ts` and `vite-plugin-wasm` as scaffolded: the plugin is harmless without `.wasm`, and the lab's validator wants examples' config identical to the template's.
- Play sounds from gameplay events in `update()` (deterministic), never from `render()`. Put `sfx: { ...audio.counts }` and `music: audio.music` in `getState()` so scenarios can assert on cues. Give players a mute key.
- three's GLTFLoader strips `.` from node names: lab_rig's bone `hand.L` is `handL` in the game. `getObjectByName('hand.L')` silently returns undefined (a ringer's hands were never pinned to her rope), so look nodes up through a helper that throws when a name is missing.
- HUD fades: drive `style.opacity` from tick counters, not CSS `transition`. Transitions don't advance in stepped `?test` runs, so a title card stayed on top of every screenshot.
- Instancing parts of a GLB (`InstancedMesh` from a template node): take each mesh's `matrixWorld` in the file, **including the template node's own transform**. The release build's meshopt quantization stores each mesh's dequantize scale/offset in its node's transform, and an orchard instanced with matrices relative to the template node rendered as squat stumps in the release build only. Dev looked right, so three judge rounds scored a bug nobody saw.
- Screen-space AO (`GTAONode` in a `RenderPipeline`) renders the scene through un-antialiased passes with noisy AO: it added grain to clouds, dark seams where spheres intersect and black specks on small flower quads, and the visual judges marked polish down more than the soft shading gained. For a soft toy look prefer soft shadows (`shadow.radius`, `normalBias`) and per-material shading; if you use GTAO, look at magnified crops of thin and intersecting geometry first.
- Replacing a GLB material in code (`new MeshStandardNodeMaterial`) drops its `side`: a double-sided terrain went back to front faces only and the whole valley vanished. Copy `side` from the old material.
- Planes added in code (painted cards, decals, shadow blobs, water) must sit ≥ 1 cm off any surface they lie on, or
  use `material.polygonOffset`. The Blender check (`blender-assets`) only sees the GLB; coplanar planes from code
  z-fight the same way.
- The loading bar uses `palette.accent` from `style.json`; give the palette an `accent` role.
- Keep all code in `import * as THREE from 'three/webgpu'`. Use addons from `three/addons/...`. Never mix in `three` (the WebGL-only build).

## TypeScript
Game code, bots and scripts are strict TypeScript (`tsconfig.json`: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`). Vite bundles `src/`; Node runs `scripts/*.ts` directly (type stripping, no build step). So:
- Only erasable syntax: no `enum`, `namespace` or constructor parameter properties (use union types and plain fields).
- Relative imports keep the `.ts` extension; type-only imports use `import type`.
- three.js types come from `@types/three`; Rapier, gltf-transform and Playwright ship their own.
- Indexing returns `T | undefined` (`noUncheckedIndexedAccess`): handle the miss, or use `!` only where the index is provably in range.
- glTF `userData` is untyped: read it with bracket access (`o.userData['collider']`) and narrow.
- Bots (`tests/scenarios/bots/*.ts`) are one arrow-function expression evaluated in the page. They may `import type { GameHooks } from '../../../src/engine/testHooks.ts'` and the game's `State`/`Action` (type imports are erased), nothing else.

## References (read when relevant)
- `references/rapier3d.md`: bodies, colliders, CCD, sensors, character control, the tuning gotchas
- `references/rapier2d.md`: switching to 2D physics (top-down/side-on games)
- `references/webgpu-notes.md`: WebGPURenderer, TSL materials, post-processing, fallback caveats
- `references/perf-budget.md`: targets and how to measure them
- `references/controls.md`: input/camera feel rules (feedback loops, dead zones, cancel, sensitivity) and how to test them with real input
Pliki w paczce (32)
  • SKILL.md 12 KB
  • assets/template/.gitignore 1 KB
  • assets/template/index.html 1 KB
  • assets/template/package.json 1 KB
  • assets/template/tsconfig.json 1 KB
  • assets/template/vite.config.ts 1 KB
  • assets/template/assets/src/.gitkeep 1 KB
  • assets/template/design/style.json 1 KB
  • assets/template/public/models/.gitkeep 1 KB
  • assets/template/scripts/build-assets.ts 2 KB
  • assets/template/scripts/generate-media.ts 46 KB
  • assets/template/scripts/preview_glb.py 4 KB
  • assets/template/scripts/release.ts 19 KB
  • assets/template/src/main.ts 4 KB
  • assets/template/src/engine/animation.ts 3 KB
  • assets/template/src/engine/assets.ts 4 KB
  • assets/template/src/engine/audio.ts 9 KB
  • assets/template/src/engine/input.ts 2 KB
  • assets/template/src/engine/levels.ts 7 KB
  • assets/template/src/engine/loading.ts 7 KB
  • assets/template/src/engine/loop.ts 2 KB
  • assets/template/src/engine/physics.ts 7 KB
  • assets/template/src/engine/renderer.ts 2 KB
  • assets/template/src/engine/style.ts 4 KB
  • assets/template/src/engine/testHooks.ts 3 KB
  • assets/template/tests/scenarios/01-boot.json 1 KB
  • references/controls.md 3 KB
  • references/perf-budget.md 1 KB
  • references/rapier2d.md 1 KB
  • references/rapier3d.md 3 KB
  • references/webgpu-notes.md 7 KB
  • scripts/scaffold.ts 2 KB

Wersje

W bazie nie ma innych skilli o nazwie web-game-runtime.

Migawka bazy z 13.11.2026 · wersja paczki e5541ffafcf1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100game-threejs-specialist
    Buduje gry 3D na WebGL i WebGPU w Three.js lub React Three Fiber, z fizyką Rapier, plikami GLB i budżetami mobilnymi.
  • 100make-web-game
    Buduje, zmienia lub naprawia grę przeglądarkową w three.js na podstawie krótkiego opisu, testuje ją w headless Chrome i iteruje do skutku.
  • 100blender-assets
    Tworzy proceduralnie modele 3D do gier webowych w Blenderze, eksportuje GLB z tagami kolizji dla Rapier i renderuje podglądy.
  • 100rapier-physics-3d
    Pomaga w fizyce 3D Rapier w Three.js: ciała sztywne, kontakty, złącza, ciągi i masy, a nie fizyka 2D.
  • 90local-three-webgl-game-3d718eed
    Buduje środowisko gry 3D w czystym Three.js z imperatywnym sterowaniem sceną, plikami GLB, fizyką i debugowaniem WebGL.
  • 903d-physics-game
    Buduje responsywne gry 3D w przeglądarce, kontrolery postaci i symulacje fizyki w React Three Fiber i Three.js.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.