✨ add Game Systems Reference wiki page
181
Game-Systems-Reference.md
Normal file
181
Game-Systems-Reference.md
Normal file
@@ -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)
|
||||
```
|
||||
Reference in New Issue
Block a user