From f7abb970fc1ac58c4d21c5151bf3bdd1d257b2df Mon Sep 17 00:00:00 2001 From: claude Date: Sun, 22 Mar 2026 14:57:58 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20add=20Game=20Systems=20Reference=20?= =?UTF-8?q?wiki=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Game-Systems-Reference.md | 181 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 Game-Systems-Reference.md diff --git a/Game-Systems-Reference.md b/Game-Systems-Reference.md new file mode 100644 index 0000000..2273062 --- /dev/null +++ b/Game-Systems-Reference.md @@ -0,0 +1,181 @@ +# Game Systems Reference + +> **Legend** +> - βœ… Implemented β€” exists in the current codebase +> - πŸ—ΊοΈ Planned β€” design exists but not yet implemented + +--- + +## Resources + +### Raw Resources + +| Resource | Source | Harvested by | Yield | +|----------|--------|--------------|-------| +| `wood` βœ… | Tree node (FOREST tile) | Villager (chop) | +2 per harvest | +| `stone` βœ… | Rock node (ROCK tile) | Villager (mine) | +2 per harvest | +| `wheat` βœ… | Wheat crop (max stage) | Villager (farm) or Player | +3 per harvest | +| `carrot` βœ… | Carrot crop (max stage) | Villager (farm) or Player | +4 per harvest | +| `wheat_seed` βœ… | Wheat harvest | β€” | +2 per harvest | +| `carrot_seed` βœ… | Carrot harvest | β€” | +1 per harvest | +| `tree_seed` βœ… | Starting stockpile | β€” | Used to plant tree seedlings | + +### Starting Stockpile βœ… + +``` +wood: 10 Β· stone: 5 Β· wheat_seed: 10 Β· carrot_seed: 5 Β· tree_seed: 5 +``` + +--- + +## Villager Jobs + +All jobs are assigned automatically based on **priority** (1 = highest) and **distance** (closest target wins within same priority). + +| Job | Trigger | Work Duration | Output | +|-----|---------|--------------|--------| +| `chop` βœ… | Tree resource exists on map | 3,000 ms | +2 wood β†’ stockpile | +| `mine` βœ… | Rock resource exists on map | 5,000 ms | +2 stone β†’ stockpile | +| `farm` βœ… | Crop at max growth stage | 1,200 ms | Crop yield β†’ stockpile | + +**Default priority on spawn:** chop 1 Β· mine 2 Β· farm 3 +**Player can reorder** priorities per villager in the villager panel. + +### Villager AI Cycle βœ… + +``` +Idle β†’ find job (priority + distance) + β†’ Walking (path to target, energy drains 0.0015/ms β‰ˆ 3/s) + β†’ Working (fixed duration, wobble animation) + β†’ Depositing (walk to nearest stockpile) + β†’ back to Idle + └─ if energy < 25 β†’ Sleeping in nearest bed (energy +0.04/ms β‰ˆ 4/s) +``` + +### Energy System βœ… + +| State | Energy change | Notes | +|-------|--------------|-------| +| Walking | βˆ’0.0015 per ms | β‰ˆ βˆ’3 per second | +| Working | no drain | Standing still | +| Sleeping | +0.04 per ms | β‰ˆ full in ~25 s | +| Sleep trigger | energy < 25 | | +| Wake trigger | energy = 100 | | + +Energy bar color: 🟒 > 60 Β· 🟠 30–60 Β· πŸ”΄ < 30 + +### Spawn Rules βœ… + +- One villager spawns per **free bed** (max population = number of beds) +- Spawn check every **8,000 ms** +- Movement speed: **75 px/s** + +--- + +## Buildings + +All buildings are placed by the player (press **B**). Costs are deducted from the stockpile. + +| Building | Cost | Tile effect | Function | +|----------|------|-------------|----------| +| `floor` βœ… | 2 wood | GRASS β†’ FLOOR | Walkable platform | +| `wall` βœ… | 3 wood + 1 stone | GRASS β†’ WALL | Impassable barrier | +| `chest` βœ… | 5 wood + 2 stone | GRASS β†’ FLOOR | Visual only (no gameplay function yet) | +| `bed` βœ… | 6 wood | β€” | Villager spawn point + sleep location | +| `stockpile_zone` βœ… | free | β€” | Villagers deposit items here | + +--- + +## Farming + +Player presses **F** to cycle farming tools. + +| Tool | Action | Requirement | Cost | +|------|--------|-------------|------| +| `hoe` βœ… | Till soil | GRASS or DARK_GRASS, no obstacles | β€” | +| `wheat_seed` βœ… | Plant wheat | TILLED_SOIL or WATERED_SOIL | 1 wheat_seed | +| `carrot_seed` βœ… | Plant carrot | TILLED_SOIL or WATERED_SOIL | 1 carrot_seed | +| `tree_seed` βœ… | Plant tree seedling | GRASS or DARK_GRASS | 1 tree_seed | +| `water` βœ… | Water soil | TILLED_SOIL or WATERED_SOIL | β€” | + +### Crops βœ… + +| Crop | Stages | Time per stage | Watered | Yield | +|------|--------|---------------|---------|-------| +| Wheat | 3 | 20,000 ms | 2Γ— faster | +3 wheat + 2 wheat_seed | +| Carrot | 3 | 25,000 ms | 2Γ— faster | +4 carrot + 1 carrot_seed | + +Watering changes the tile to WATERED_SOIL which doubles growth speed. +At max stage, a villager (farm job) or the player can harvest. + +--- + +## Tree Seedlings βœ… + +Planted with the `tree_seed` tool on GRASS / DARK_GRASS tiles. + +| Stage | Duration | Visual | +|-------|----------|--------| +| 0 | 60,000 ms | Sprout | +| 1 | 60,000 ms | Sapling | +| 2 | β€” | Converts automatically | + +At stage 2 the seedling converts to a **FOREST tile** with a new tree resource (hp 3), which villagers can immediately chop. +Total growth time: ~2 minutes. No interaction needed after planting. + +--- + +## Terrain & Tiles + +| Tile | ID | Passable | Notes | +|------|----|----------|-------| +| DEEP_WATER | 0 | No | | +| SHALLOW_WATER | 1 | No | | +| SAND | 2 | Yes | | +| GRASS | 3 | Yes | Default terrain | +| DARK_GRASS | 4 | Yes | After tree felled; reverts to GRASS after 5 min | +| FOREST | 5 | No | Contains tree resource (70% spawn chance) | +| ROCK | 6 | No | Contains rock resource (50% spawn chance) | +| FLOOR | 7 | Yes | Built by player | +| WALL | 8 | No | Built by player | +| TILLED_SOIL | 9 | Yes | Ready for planting | +| WATERED_SOIL | 10 | Yes | 2Γ— crop growth | + +**Tile recovery:** DARK_GRASS β†’ GRASS after **300,000 ms (5 min)**. + +--- + +## World & Engine + +| Constant | Value | +|----------|-------| +| Tile size | 32 px | +| World size | 512 Γ— 512 tiles (16,384 Γ— 16,384 px) | +| Player speed | 180 px/s | +| Camera lerp | 0.09 | +| Autosave interval | 30,000 ms | + +Terrain generated procedurally via **Simplex noise** at world creation. + +--- + +## Resource Flow + +``` +WOOD / STONE + Tree/Rock (terrain) β†’ Villager chops/mines (3–5 s) β†’ carrying inventory + β†’ deposit at stockpile + +FOOD / SEEDS + Player tills & plants (costs 1 seed) β†’ crop grows (3 stages, 20–25 s each) + β†’ optional: water (2Γ— speed) + β†’ villager farms (1.2 s) OR player harvests β†’ stockpile + +TREES (renewable) + Player plants tree_seed β†’ seedling grows (~2 min, 2 stages Γ  60 s) + β†’ auto-converts to FOREST tile + tree resource β†’ villagers can chop + +BUILDINGS + Stockpile resources β†’ player places building β†’ function unlocked + (beds β†’ more villagers, stockpile zones β†’ deposit destinations) +```