Fish per water type in data/fish.json; worldlets design
- data/fish.json: fish, weights, dawn/dusk odds, bite timing and minimum depth per water type; ItemDB.define_water() registers them - world.water_at(x, z) answers lake / sea / dry land; the float uses it, so a worldlet with a sea only needs a "sea" entry - Clear messages for shallow water and water with nothing to catch - Lake fish: more of them, bigger, nearer the shore, jumping with splash rings - docs/WORLDLETS_DESIGN.md: proposal for data-defined world types
This commit is contained in:
Paul Bailey
165
docs/WORLDLETS_DESIGN.md
Normal file
165
docs/WORLDLETS_DESIGN.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Worldlets design
|
||||
|
||||
Status: **proposal**. Nothing here is built yet, apart from the first piece
|
||||
of groundwork (`world.water_at()` and `data/fish.json`, see §6).
|
||||
|
||||
## 1. What a worldlet is
|
||||
A **worldlet** is a small, complete world type: a ~320 m playable area with
|
||||
its own shape, water, climate, wildlife and features, generated from a seed
|
||||
like today's island. The current map becomes the first worldlet, **"Valley"**:
|
||||
a mountain ring, a lake and a sea cliff. Others can differ in kind, not just
|
||||
in seed:
|
||||
|
||||
| Worldlet | Shape | Water | Twist |
|
||||
|---|---|---|---|
|
||||
| **Valley** (today) | mountain ring + sea cliff | lake | wolves' den in the rim |
|
||||
| **Cove** | low hills down to a sandy bay | sea + harbour, a stream | sea fishing, a pier, tides later |
|
||||
| **Highlands** | plateau, cliffs, a tarn | small cold lake | snow most days, harsher nights |
|
||||
| **Marsh** | flat, reedy, pools | many shallow pools | fog, insects, bog iron later |
|
||||
|
||||
A worldlet is **data plus a few generator building blocks**, not a new
|
||||
scene with its own code. That keeps the game's systems shared (building,
|
||||
survival, creatures, saving) and makes worldlets addable by addons later
|
||||
(§7).
|
||||
|
||||
## 2. The big decision: one worldlet per save, or linked worldlets?
|
||||
|
||||
**A. One worldlet per save.** New World asks for a name, a seed and a
|
||||
worldlet type. Simple, and it fits everything already built.
|
||||
|
||||
**B. Linked worldlets in one save.** Several worldlets form one world, and
|
||||
you travel between them (a mountain pass, a cave tunnel, a boat). Each keeps
|
||||
its own state. More exciting, but much more work, especially in M2: a server
|
||||
would have to simulate several places at once, or keep all players together.
|
||||
|
||||
**Recommendation: build A first, with a save layout that allows B later.**
|
||||
Each worldlet's state goes in its own file from day one
|
||||
(`worlds/<id>/worldlets/<worldlet>.json`), and the player's own state moves
|
||||
to `worlds/<id>/player.json`. Then B is "add travel and a second file",
|
||||
not "migrate every save".
|
||||
|
||||
## 3. Definition format
|
||||
`data/worldlets/<id>.json`. Every number that's an `@export` on
|
||||
`terrain.gd` today moves here, plus the lists that are hard-coded:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "cove",
|
||||
"name": "Cove",
|
||||
"description": "Low hills running down to a sheltered bay.",
|
||||
"size": 320,
|
||||
"terrain": {
|
||||
"base": {"height_scale": 7.0, "octaves": 4},
|
||||
"boundary": [
|
||||
{"type": "mountains", "from_deg": 60, "to_deg": 300, "height": 50},
|
||||
{"type": "beach", "from_deg": 300, "to_deg": 60, "slope": 0.08}
|
||||
],
|
||||
"features": [
|
||||
{"type": "cove", "angle_deg": 0, "width": 60},
|
||||
{"type": "stream", "from": "mountains", "to": "cove"}
|
||||
]
|
||||
},
|
||||
"water": {"sea_level": -1.5, "lakes": []},
|
||||
"climate": {"cold_day_chance": 0.1, "snowline": 45, "day_length": 1200},
|
||||
"wildlife": {
|
||||
"budget": {"rabbit": 5, "deer": 3, "boar": 2},
|
||||
"wolves": {"den": "rim", "den_day": 3, "hunt_day": 5}
|
||||
},
|
||||
"places": [{"type": "pier", "at": "cove"}],
|
||||
"spawn": {"near": "cove", "facing": "sea"}
|
||||
}
|
||||
```
|
||||
|
||||
Generator **building blocks** (GDScript, shared by all worldlets): base
|
||||
hills, mountain rim, sea cliff, beach slope, cove/bay, lake basin, stream
|
||||
bed, plateau. A worldlet only picks and parameterises them, so it can't do
|
||||
anything a block can't.
|
||||
|
||||
## 4. What changes in the code
|
||||
Most game code already asks the terrain generic questions:
|
||||
`sample_height`, `sample_normal`, `inside_boundary` and `find_spawn`. The
|
||||
work is in the places that know about *this* island's single lake and
|
||||
cliff. Today:
|
||||
|
||||
| Assumption | Used in | Becomes |
|
||||
|---|---|---|
|
||||
| one lake at `water_level` | player (swimming), creature, spawner, den, build_system, props, lake_fish, world | `world.water_at(x, z)` (done for fishing) |
|
||||
| `lake_center` / `lake_radius` | lake_fish, world (views) | the water bodies list |
|
||||
| `sea_angle_deg`, `coast_point` | props (sea stacks, cliff-top strip), world (views) | the boundary segment list |
|
||||
| `snow_height` | props, spawner, weather | `climate.snowline` |
|
||||
| `play_radius` | props, den | boundary queries |
|
||||
|
||||
The steps:
|
||||
1. **Terrain pipeline.** `terrain.gd` becomes a runner that stacks the
|
||||
chosen building blocks into the height grid. The grid, collision,
|
||||
`sample_height` and the boundary wall stay exactly as they are.
|
||||
2. **A `WorldInfo` API** on the world node, for everything outside terrain:
|
||||
`water_at`, `water_bodies()`, `boundary_at(angle)`, `features(type)`,
|
||||
`climate`. No system reads terrain exports directly any more.
|
||||
3. **Water bodies.** Each lake, pond and the sea is a body with a surface,
|
||||
shape and type. The water mesh is built per body. Swimming, the "too
|
||||
deep" check, animal steering and fishing all go through `water_at`.
|
||||
4. **Props and places by feature.** Scenery reads densities from the
|
||||
definition. The den, the sea stacks and (in Cove) the pier are "places"
|
||||
positioned by features, not hard-coded angles.
|
||||
5. **Saves.** `meta.json` gains `"worldlet": "valley"`. Older saves default
|
||||
to Valley, so nothing breaks.
|
||||
6. **New World screen.** Pick a worldlet type (with a short description and
|
||||
a preview render), then name and seed as now.
|
||||
|
||||
## 5. The Cove and sea fishing
|
||||
- **Beach boundary.** Sand slopes gently into shallow water. You can wade
|
||||
and swim out until the water is deep, and then a current carries you back
|
||||
(the beach equivalent of the invisible wall, with a toast).
|
||||
- **Harbour.** A sheltered bay with a generated wooden pier. The pier is
|
||||
built from the building pieces, so it's "placed by the world" and can't
|
||||
be dismantled.
|
||||
- **Sea fish** in `data/fish.json` under `"sea"`: mackerel (common),
|
||||
cod (bigger, deeper water), and maybe crab pots later. Casting from the
|
||||
pier reaches deep water. The fishing code needs no changes: it already
|
||||
asks `water_at` what it landed in and looks up that water's fish.
|
||||
- Later: tides (sea level shifting slowly), a raft or rowing boat, and
|
||||
driftwood on the beach.
|
||||
|
||||
## 6. Done already (groundwork)
|
||||
- `world.water_at(x, z)` returns `{type, surface, depth}` for the lake and
|
||||
the sea, and fishing uses it instead of `terrain.water_level`.
|
||||
- `data/fish.json` holds the fish per water type, bite timings and
|
||||
dawn/dusk weights. `ItemDB.define_water()` registers a water's fish, so an
|
||||
addon or a worldlet can add "sea" without code.
|
||||
|
||||
## 7. How it fits the roadmap
|
||||
- **Before M2 (recommended):** steps 1-6 for Valley alone, with no visible
|
||||
change, then the Cove. Doing the refactor before multiplayer means M2
|
||||
replicates "worldlet id + seed + edits", not one hard-coded island.
|
||||
- **M2:** the server loads one worldlet per save (option A). Clients
|
||||
regenerate it from id + seed, which is the same determinism we rely on
|
||||
now.
|
||||
- **M3 (addons):** `define_worldlet()` takes the same JSON. Addons can only
|
||||
combine building blocks, so a worldlet addon can't run arbitrary code in
|
||||
the generator.
|
||||
- **Option B (linked worldlets)** fits after M2, once we know how the
|
||||
server handles players in different places.
|
||||
|
||||
## 8. Phasing and tests
|
||||
| Phase | Delivers | Done when |
|
||||
|---|---|---|
|
||||
| **W0** | terrain pipeline + WorldInfo API; Valley defined in JSON | seed 1337 generates the **same height grid** as today (a hash test), and all 9 suites still pass |
|
||||
| **W1** | worldlet picked on New World and saved in meta; old saves = Valley | load an old save and a new Valley save; both play |
|
||||
| **W2** | water bodies (several per world), beach boundary block, swim-back current | a test worldlet with two ponds and a beach passes the boundary and terrain-edge tests |
|
||||
| **W3** | **Cove** worldlet: bay, stream, pier place, sea fish | you catch a mackerel off the pier |
|
||||
| **W4** | (optional) Highlands / Marsh | each passes the shared suites |
|
||||
| **W5** | (after M2, optional) linked worldlets and travel | walk through a pass from Valley into Cove and back |
|
||||
|
||||
Every existing suite runs per worldlet (boundary, terrain edges, survival,
|
||||
building, wildlife, fishing), so a new worldlet can't ship with a hole in
|
||||
its edge or animals that spawn in the sea.
|
||||
|
||||
## 9. Questions for you
|
||||
1. **A or B?** One worldlet per save to start, or do you want travel between
|
||||
them early? (Recommendation: A, with the save layout ready for B.)
|
||||
2. **Worldlet size:** keep ~320 m, or let some be bigger?
|
||||
3. **Difficulty per worldlet:** should harsher worldlets (Highlands) bring
|
||||
wolves sooner, or keep the same grace period everywhere?
|
||||
4. **Which second worldlet first:** Cove (sea fishing, the beach you
|
||||
mentioned) is my suggestion.
|
||||
Reference in New Issue
Block a user