Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
69 commits
Select commit Hold shift + click to select a range
fc6869f
docs(phase-15): create plans for green baseline and runtime-in-library
DanielMartinezSebastian Oct 10, 2026
18fcf71
test(demo): realign publicApi contract tests with injected adapters
DanielMartinezSebastian Oct 10, 2026
0f581c5
refactor(renderer): extract attachAudioSystem from useAudioSystem
DanielMartinezSebastian Oct 10, 2026
c333591
fix(demo): resolve react-hooks lint errors in runtime components
DanielMartinezSebastian Oct 10, 2026
d559a47
chore(demo): remove explicit any and unused imports
DanielMartinezSebastian Oct 10, 2026
da799d3
fix(core): guard process.env access and add agnosticism test
DanielMartinezSebastian Oct 10, 2026
5d76ff6
chore(phase-15): add CI, untrack dist and build packages on install
DanielMartinezSebastian Oct 10, 2026
94d4d69
docs(phase-15): resync phase status, index and inherited gates
DanielMartinezSebastian Oct 10, 2026
a281f4f
docs(adr): accept 0009 runtime lives in packages
DanielMartinezSebastian Oct 10, 2026
07ad621
docs(phase-15): record owner-verified scene transition in smoke gate
DanielMartinezSebastian Oct 10, 2026
d344e07
feat(core): add framework-agnostic game runtime factory
DanielMartinezSebastian Oct 10, 2026
13540e9
fix(demo): route game persistence through the storage adapter
DanielMartinezSebastian Oct 10, 2026
6e6f6cb
refactor(demo): delete render copies duplicated from the renderer
DanielMartinezSebastian Oct 10, 2026
fb70e96
docs(phase-15): close phase after owner browser verification
DanielMartinezSebastian Oct 10, 2026
f8b1060
feat(core): implement player:stop command
DanielMartinezSebastian Oct 10, 2026
d1c6374
refactor(renderer): move state hooks to renderer and make publicApi a…
DanielMartinezSebastian Oct 10, 2026
5587460
refactor(demo): derive scene and item types from engine-core
DanielMartinezSebastian Oct 10, 2026
9ab9793
feat(renderer): add configurable CharacterSprite and character prop
DanielMartinezSebastian Oct 10, 2026
e6abc94
refactor(demo): declare sounds in data and pass character to runtime
DanielMartinezSebastian Oct 10, 2026
5012df5
refactor(core): make demo use core inventory rules and drop its copy
DanielMartinezSebastian Oct 10, 2026
95e55f4
docs(phase-16): record owner smoke after waves A-C and audio decision
DanielMartinezSebastian Oct 10, 2026
27ad70b
feat(core): emit item:pickedUp on pickup and wire declarative audio
DanielMartinezSebastian Oct 10, 2026
08e8f5c
feat(core): add spawn on scene:set and default dialog/inventory UI st…
DanielMartinezSebastian Oct 10, 2026
7c4e510
refactor(renderer): move scene, camera and drop-target components fro…
DanielMartinezSebastian Oct 10, 2026
61cb7f5
refactor(demo): adopt core UI stores and resolve items from the runtime
DanielMartinezSebastian Oct 10, 2026
99c9a62
feat(core): add reactive inventory and placed-items stores with port …
DanielMartinezSebastian Oct 10, 2026
5fee13e
refactor(renderer): move scene seeding and persistence into useSceneR…
DanielMartinezSebastian Oct 10, 2026
100bbcc
test(demo): add headless playthrough smoke with audio assertions
DanielMartinezSebastian Oct 10, 2026
75429ea
refactor(renderer): move transition system from demo with injected ex…
DanielMartinezSebastian Oct 10, 2026
43204da
test(demo): cover inventory drag, placing and returning items in smoke
DanielMartinezSebastian Oct 10, 2026
a947d2e
refactor(demo): keep inventory and placed items in core stores
DanielMartinezSebastian Oct 10, 2026
095e677
refactor(renderer): move inventory runtime hook from demo
DanielMartinezSebastian Oct 10, 2026
4d37ea4
feat(renderer): make GameViewport a playable game composition
DanielMartinezSebastian Oct 10, 2026
7651266
feat(demo): add example-minimal route that imports only the packages
DanielMartinezSebastian Oct 10, 2026
37b4f7a
fix(renderer): make the package installable and asset-free outside th…
DanielMartinezSebastian Oct 10, 2026
ae2c0ab
docs(phase-16): rewrite consumption docs and changelogs for 0.5.0
DanielMartinezSebastian Oct 10, 2026
fd841cf
docs(phase-16): close phase with final gate evidence and retrospective
DanielMartinezSebastian Oct 10, 2026
debcd19
docs(phase-17): create modular plan for narrative primitives
DanielMartinezSebastian Oct 10, 2026
1022a83
docs(phase-17): record owner decisions on narrative model and story demo
DanielMartinezSebastian Oct 10, 2026
9a821a9
docs(phase-18): record asset pack research for the story demo
DanielMartinezSebastian Oct 10, 2026
c36331a
feat(core): add ClockPort with system and headless implementations
DanielMartinezSebastian Oct 10, 2026
b37c6b9
feat(core): add world state store with flags and visited scenes
DanielMartinezSebastian Oct 10, 2026
206d8a7
feat(core): add declarative conditions with a pure evaluator
DanielMartinezSebastian Oct 10, 2026
b0d916f
feat(core): add single versioned save with legacy migration
DanielMartinezSebastian Oct 10, 2026
5339478
chore(demo): add CC0 item icon packs as art sources for the story demo
DanielMartinezSebastian Oct 10, 2026
b04790e
docs(phase-18): record decision to keep the watermarked town background
DanielMartinezSebastian Oct 10, 2026
ac30f66
feat(core): add script actions and a cancellable sequencer
DanielMartinezSebastian Oct 10, 2026
20e154b
feat(core): add scene hotspots with verbs and real inventory commands
DanielMartinezSebastian Oct 10, 2026
77bdcb6
feat(renderer): emit walk completed and aborted for path walks
DanielMartinezSebastian Oct 10, 2026
655232a
feat(core): add dialogue trees with conditional and one-shot choices
DanielMartinezSebastian Oct 10, 2026
7f73743
feat(core): add inventory item combination
DanielMartinezSebastian Oct 10, 2026
e02100f
fix(renderer): stop the walk clip from flickering between directions
DanielMartinezSebastian Oct 10, 2026
62f3ae8
chore(demo): add the Sci Fi Level background as an art source
DanielMartinezSebastian Oct 10, 2026
3494931
feat(core): add declarative scene rules for seeding, entry and transi…
DanielMartinezSebastian Oct 10, 2026
4de2ea3
chore(demo): add the Helix male character sheet as an art source
DanielMartinezSebastian Oct 10, 2026
f9af7c2
refactor(core): declare every outcome carried by item:dropped
DanielMartinezSebastian Oct 11, 2026
c382b05
feat: add scene NPCs as hotspots with a sprite
DanielMartinezSebastian Oct 11, 2026
576e3a2
feat(core): validate game content for broken references at startup
DanielMartinezSebastian Oct 11, 2026
b11abf3
feat(renderer): make hotspots clickable with a verb menu
DanielMartinezSebastian Oct 11, 2026
df45538
feat(renderer): add dialogue choices UI and useDialogue
DanielMartinezSebastian Oct 11, 2026
c31612d
fix(renderer): emit dialog:dismissed when the speech bubble closes
DanielMartinezSebastian Oct 11, 2026
5368eb7
feat(core): add createPlaythrough and a headless mini-adventure test
DanielMartinezSebastian Oct 11, 2026
c161c61
fix(core): do not validate the interaction label of placed items
DanielMartinezSebastian Oct 11, 2026
ef865ce
refactor(demo): move scene rules to data and saves to a single snapshot
DanielMartinezSebastian Oct 11, 2026
165eade
fix: cover the whole NPC sprite with its click box and translate verb…
DanielMartinezSebastian Oct 11, 2026
63e2e41
feat(demo): add a test NPC, hotspot and item combination
DanielMartinezSebastian Oct 11, 2026
e543069
feat(demo): add the Sci-Fi Lab test scene with the Helix NPC
DanielMartinezSebastian Oct 11, 2026
90fa47c
docs: add the authoring guide and document the 0.6.0 narrative API
DanielMartinezSebastian Oct 11, 2026
08e461b
chore(release): 0.6.0 and close phase 17
DanielMartinezSebastian Oct 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
48 changes: 48 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: CI

on:
push:
branches:
- main
pull_request:

concurrency:
group: ${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
verify:
runs-on: ubuntu-latest
env:
NEXT_TELEMETRY_DISABLED: 1

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm

- name: Install dependencies
run: npm ci

- name: Build packages
run: npm run build:packages

- name: Run tests
run: npm test

- name: Type-check
run: npm run typecheck

- name: Run linter
run: npm run lint

- name: Build web-demo
run: npm run build -w apps/web-demo
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-debug.log*
*.log

# env files (can opt-in for committing if needed)
.env*
Expand All @@ -44,3 +45,6 @@ next-env.d.ts

# Claude Code worktrees (prevent VS Code from indexing them)
.claude/worktrees/

# build output de los paquetes — se regenera con npm run build:packages
packages/*/dist/
28 changes: 16 additions & 12 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Point & Click Game Engine

**Versión**: 2.0-dev | **Estado**: Desarrollo activo | **Owner**: Daniel Martínez Sebastián
**Versión**: 0.6.0 | **Estado**: Desarrollo activo | **Owner**: Daniel Martínez Sebastián

Librería agnóstica al framework para juegos point-and-click 2D/2.5D, con primera implementación en R3F. La demo R3F vive en `apps/web-demo/` dentro del monorepo para evaluar engine y demo en paralelo.

Expand All @@ -23,9 +23,9 @@ Dos objetivos concurrentes que NO deben sabotearse mutuamente:
┌────────────────────────────────────────────┐
│ Presentación / UI (apps/web-demo) │ ← InventoryUI, Joystick, DebugOverlay
├────────────────────────────────────────────┤
│ Renderer R3F (apps/web-demo) │ ← GameTouchCanvas, useFrame, Three.js
│ Renderer R3F (engine-renderer-r3f) │ ← GameViewport, hooks, useFrame, Three.js
├────────────────────────────────────────────┤
│ Core (packages/engine-core) AGNÓSTICO │ ← state, rules, pathfinding, events
│ Core (packages/engine-core) AGNÓSTICO │ ← runtime, state, rules, pathfinding, events
├────────────────────────────────────────────┤
│ Platform Adapters (apps/web-demo) │ ← storage, clipboard, timer (web)
└────────────────────────────────────────────┘
Expand All @@ -46,9 +46,10 @@ Dos objetivos concurrentes que NO deben sabotearse mutuamente:

| Tipo | Ubicación | Ejemplos |
|------|-----------|----------|
| **Core** (agnóstico) | `packages/engine-core/` | rules, sceneStore, findPath, types |
| **Renderer** (R3F) | `apps/web-demo/app/lib/engine/runtime/` y `/render/` | useFrame loops, Canvas, sprites |
| **Core** (agnóstico) | `packages/engine-core/src/` (runtime en `game/runtime/`) | createGameRuntime, rules, sceneStore, findPath, types |
| **Renderer** (R3F) | `packages/engine-renderer-r3f/src/` (`viewport/`, `hooks/`, `scene/`, `sprite/`) | GameViewport, useFrame loops, Canvas, sprites |
| **UI** (React) | `apps/web-demo/app/components/` | Joystick, InventoryUI, panels |
| **Contenido y composición** (demo) | `apps/web-demo/demo-content/`, `apps/web-demo/app/lib/engine/runtime/` | escenas, ítems, opciones del viewport, puertas, editores |
| **Platform** (web) | `apps/web-demo/app/lib/platform-web.ts` | localStorage, clipboard adapters |

**Detalles**: `docs/architecture/03-rules-core-vs-render.md`
Expand All @@ -57,11 +58,13 @@ Dos objetivos concurrentes que NO deben sabotearse mutuamente:

## API Pública (Contrato Estable)

Frontera pública en `apps/web-demo/app/lib/engine/publicApi.ts`. **No romper sin issue + migración**.
Vive en los paquetes: runtime en `packages/engine-core/src/game/runtime/`, viewport y hooks en `packages/engine-renderer-r3f/src/index.ts`. `apps/web-demo/app/lib/engine/publicApi.ts` es un barrel de compatibilidad que re-exporta ambos. **No romper sin issue + migración**.

Exporta: `createGameRuntime`, `registerScene`, `registerItem`, `registerRule`, `getGameState`, `getGameActions`, `getGameRuntime`, `useGameState`, `useGameActions`, `GameViewport`.
- `engine-core` exporta: `createGameRuntime`, `getGameRuntime`, `registerScene`, `registerItem`, `registerRule`, `getGameState`, `getGameActions`.
- `engine-renderer-r3f` exporta: `GameViewport`, `useGameViewportController`, `GameViewportView`, `useGameState`, `useGameActions`.
- El handle de `createGameRuntime` trae `executeCommand`, `on`, `emit`, `dispose`.

**Phase 4 añade** (via handle devuelto por `createGameRuntime`): `executeCommand`, `on`, `emit`, `dispose`.
Lista completa: `docs/LIBRARY_API_CONTRACT_V1.md`.

**Detalles**: `docs/architecture/02-public-api.md`

Expand Down Expand Up @@ -107,10 +110,12 @@ Ver: `docs/workflow/pre-commit-checklist.md`

## Versionado

- **v0.1.x**: Demo R3F funcional (actual)
- **v0.1.x**: Demo R3F funcional
- **v0.2.x**: `engine-core` extraído del monorepo
- **v0.3.x**: Renderer abstraction (interfaces agnósticas)
- **v0.4.x**: Bidireccionalidad web ↔ juego
- **v0.5.x**: Runtime en los paquetes, `GameViewport` jugable
- **v0.6.x**: Narrativa declarativa: hotspots, NPCs, diálogos, guardado único (actual)
- **v1.0.0**: Publicación en npm

---
Expand All @@ -137,8 +142,6 @@ Ver: `docs/workflow/pre-commit-checklist.md`
└── decisions/ # ADRs ligeros
```

**Nota**: la estructura monorepo se materializa en Fase 2. Estado actual: app Next.js plana.

---

## Documentos Clave
Expand All @@ -153,7 +156,8 @@ Ver: `docs/workflow/pre-commit-checklist.md`
| Delegar subagentes | `docs/workflow/how-to-spawn-subagent.md` |
| Hacer commit | `docs/workflow/commit-convention.md` |
| Decisiones tomadas | `docs/decisions/` (ADRs) |
| Fase activa | `docs/phases/phase-4-bidirectional-web-game/` |
| Escribir contenido (escenas, diálogos, ítems) | `docs/authoring/README.md` |
| Fase activa | `docs/phases/phase-18-story-demo/` |

---

Expand Down
Loading
Loading