docs: fleshed out agents.md

2026-04-19 18:36:10 +08:00
parent 1e1d04777f
commit a82b6b0685
2 changed files with 96 additions and 7 deletions
@@ -0,0 +1,68 @@
+# AGENTS.md - slay-the-spire-like
+
+Roguelike deckbuilder combining Slay the Spire combat with Backpack Hero grid inventory.
+
+## Architecture
+
+Three-layer design: **system** (content-agnostic) → **data** (CSV content) → **dialogues** (Yarn Spinner).
+
+### System Layer (`system/`)
+
+| Module | Files | Responsibility |
+|---|---|---|
+| `combat/` | types.ts, effects.ts, triggers.ts, prompts.ts | Combat state, effects pipeline, middleware triggers |
+| `deck/` | types.ts, factory.ts, index.ts | Deck state management |
+| `grid-inventory/` | types.ts, transform.ts, index.ts | Grid backpack, shape collision, adjacency |
+| `map/` | types.ts, generator.ts, index.ts | Procedural node generation (point crawl) |
+| `progress/` | types.ts, encounter.ts, index.ts | Adventure progress, node traversal |
+| `utils/` | parse-shape.ts, shape-collision.ts | Shape parsing and collision detection |
+| `types.ts` | — | `EffectData`, `EffectLifecycle`, `EnemyData`, `CardData`, `IntentData`, `EncounterData`, `ItemData` |
+
+### Data Layer (`data/desert/`)
+
+All content via CSV (loaded by `inline-schema`):
+
+| File | Content |
+|---|---|
+| `card.csv` | Card definitions |
+| `effect.csv` | Effect definitions |
+| `enemy.csv` | Enemies + intents |
+| `intent.csv` | Intent definitions |
+| `item.csv` | Equipment items |
+| `encounter.csv` | Encounter nodes |
+
+### Triggers (`data/desert/triggers/`)
+
+Middleware hooks extending the base trigger system:
+
+| File | Hooks |
+|---|---|
+| `effect.ts` | Orchestrator — calls all sub-modules |
+| `instant.ts` | `onEffectApplied` — attack, draw, gainEnergy, removeWound, summon, etc. |
+| `damage.ts` | `onDamage` — block, spike, expose, aim, roll, charge, molt, tailSting, energyDrain |
+| `turn-start.ts` | `onTurnStart` — discard, defendNext, energyNext, drawNext |
+| `card-events.ts` | `onEnemyIntent`, `onCardPlayed`, `onCardDiscarded`, `onDamage` — storm, crossbow, burnForEnergy, sandwormKing, vulture |
+
+### Dialogue Layer (`data/desert/dialogues/`)
+
+`story.yarn` — branching encounter dialogues (inside `dialogues.yarnproject`). Commands resolve via `tryAnswerPrompt`.
+
+## Key Mechanics
+
+- **Energy**: 3/turn, spent on weapon/armor/tool cards
+- **Uses**: Consumable cards use `uses` cost type instead of energy; tracked as `depletion` on `GameItemMeta`
+- **Grid adjacency**: Items buff adjacent items (e.g. burnForEnergy consumes adjacent item on card play)
+- **Effect lifecycles**: `instant`, `temporary`, `lingering`, `permanent`, `posture`, `item`, `itemTemporary`, `itemUntilPlay`, `itemUntilDiscard`, `itemPermanent`
+- **Trigger pipeline**: `createMiddlewareChain` with `use(async (ctx, next) => ...)` pattern
+- **Cards from items**: `GameCard` instances are generated from `GameItem` inventory items via deck factory
+
+## Testing
+
+Tests live in `tests/samples/slay-the-spire-like/`:
+- `combat/effects.test.ts` — effect application, upkeep, posture damage
+- `combat/triggers.test.ts` — full desert trigger integration tests
+- `deck/factory.test.ts` — deck creation
+- `grid-inventory.test.ts` — placement, adjacency, collision
+- `map/generator.test.ts` — procedural generation
+- `utils/shape-utils.test.ts` — shape parsing
+- `data/index.test.ts` — data loading validation