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

data/fish.json

@@ -0,0 +1,29 @@
+{
+  "_comment": "Fishing by water type. world.water_at() says which type a spot is; a type with no entry has no fish. Weights are relative. 'dawn_dusk' replaces the weight at dawn (05:00-08:30) and dusk (17:00-20:30). Bite waits are seconds, scaled by the modifiers.",
+  "modifiers": {
+    "dawn_dusk_wait": 0.6,
+    "rain_wait": 0.8,
+    "missed_wait": 1.3
+  },
+  "waters": {
+    "lake": {
+      "min_depth": 0.5,
+      "bite_wait": [
+        5.0,
+        14.0
+      ],
+      "fish": [
+        {
+          "id": "perch",
+          "weight": 78,
+          "dawn_dusk": 60
+        },
+        {
+          "id": "trout",
+          "weight": 22,
+          "dawn_dusk": 40
+        }
+      ]
+    }
+  }
+}

docs/SURVIVAL_DESIGN.md

@@ -218,7 +218,10 @@ Built in M1b (`scripts/player/survival.gd`), current numbers:
   just reels in. Walking more than about 30 m off snaps the line, and
   switching away from the rod reels in.
 - Catch: perch (common) and trout (22%, or 40% at dawn and dusk). Grill
-  them at a campfire. A few fish swim visibly in the lake.
+  them at a campfire. A few fish swim visibly in the lake, and some jump.
+- Fish, weights and bite timing live in `data/fish.json` per water type.
+  The float asks `world.water_at()` what it landed in (lake, sea...), so a
+  worldlet with a sea only needs a "sea" entry there (docs/WORLDLETS_DESIGN.md).
 
 ### 2.8c Mixed diet *(built)*
 Every food belongs to a group: **meat** (raw meat 8, cooked 40), **fish**

docs/WORLDLETS_DESIGN.md

@@ -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.

scripts/core/item_db.gd

@@ -14,11 +14,14 @@ const ICON_SIZE := 96
 var items: Dictionary = {}     # id -> definition Dictionary
 var recipes: Dictionary = {}   # id -> recipe Dictionary (insertion order kept)
 var icons: Dictionary = {}     # id -> Texture2D
+## Fishing by water type (data/fish.json): {"modifiers": {...}, "waters": {type: {...}}}.
+var fishing: Dictionary = {"modifiers": {}, "waters": {}}
 var _item_mat: StandardMaterial3D
 
 func _ready() -> void:
 	_load("res://data/items.json", "items", define_item)
 	_load("res://data/recipes.json", "recipes", define_recipe)
+	_load_fishing("res://data/fish.json")
 	if DisplayServer.get_name() != "headless":
 		_render_icons.call_deferred()
 
@@ -51,6 +54,31 @@ func define_recipe(r: Dictionary) -> void:
 	r.station = String(r.get("station", ""))
 	recipes[r.id] = r
 
+func _load_fishing(path: String) -> void:
+	var data = JSON.parse_string(FileAccess.get_file_as_string(path))
+	if typeof(data) != TYPE_DICTIONARY or not data.has("waters"):
+		push_error("ItemDB: could not parse %s" % path)
+		return
+	fishing.modifiers = data.get("modifiers", {})
+	for water in data.waters:
+		define_water(water, data.waters[water])
+
+## Registers (or replaces) the fish for one water type. Same shape an addon
+## would use to add, say, a "swamp" water with its own catch.
+func define_water(water: String, d: Dictionary) -> void:
+	var fish: Array = []
+	for f in d.get("fish", []):
+		if not items.has(f.get("id", "")):
+			push_error("ItemDB: fish '%s' in water '%s' is not an item" % [f.get("id", "?"), water])
+			continue
+		fish.append({"id": f.id, "weight": float(f.get("weight", 1)), "dawn_dusk": float(f.get("dawn_dusk", f.get("weight", 1)))})
+	var w: Array = d.get("bite_wait", [5.0, 14.0])
+	fishing.waters[water] = {"min_depth": float(d.get("min_depth", 0.5)), "bite_wait": [float(w[0]), float(w[1])], "fish": fish}
+
+## The fishing table for a water type ({} = nothing to catch there).
+func water_fishing(water: String) -> Dictionary:
+	return fishing.waters.get(water, {})
+
 func get_item(id: String) -> Dictionary:
 	return items.get(id, {})
 

scripts/fishing/bobber.gd

@@ -12,9 +12,11 @@ extends Node3D
 ## A line is drawn from the rod tip each frame (hands.gd gives the tip).
 
 const BITE_WINDOW := 1.5
-const MIN_DEPTH := 0.5            ## water this deep under the float, or no fish
 const LINE_LENGTH := 26.0
 
+var water_type := ""              ## "lake", "sea"... (world.water_at)
+var table: Dictionary = {}        ## that water's fishing table (ItemDB.water_fishing)
+
 var world: Node3D
 var player: Node3D
 var state := "flying"
@@ -59,20 +61,34 @@ func _physics_process(delta: float) -> void:
 func _process(_delta: float) -> void:
 	_draw_line()
 
-## How long until the next bite (seconds).
+func _dawn_dusk() -> bool:
-func _next_wait() -> float:
 	var h: float = world.day_night.hours()
-	var k := 1.0
+	return (h > 5.0 and h < 8.5) or (h > 17.0 and h < 20.5)
-	if (h > 5.0 and h < 8.5) or (h > 17.0 and h < 20.5):
-		k *= 0.6                      # fish feed at dawn and dusk
-	if world.weather.precip > 0.3:
-		k *= 0.8
-	return rng.randf_range(5.0, 14.0) * k
 
+## How long until the next bite (seconds), from data/fish.json.
+func _next_wait() -> float:
+	var mods: Dictionary = ItemDB.fishing.modifiers
+	var w: Array = table.get("bite_wait", [5.0, 14.0])
+	var k := 1.0
+	if _dawn_dusk():
+		k *= float(mods.get("dawn_dusk_wait", 0.6))   # fish feed at dawn and dusk
+	if world.weather.precip > 0.3:
+		k *= float(mods.get("rain_wait", 0.8))
+	return rng.randf_range(w[0], w[1]) * k
+
+## A weighted pick from this water's fish (dawn/dusk weights when they apply).
 func _pick_fish() -> String:
-	var h: float = world.day_night.hours()
+	var fish: Array = table.get("fish", [])
-	var trout := 0.4 if (h > 5.0 and h < 8.5) or (h > 17.0 and h < 20.5) else 0.22
+	var key := "dawn_dusk" if _dawn_dusk() else "weight"
-	return "trout" if rng.randf() < trout else "perch"
+	var total := 0.0
+	for f in fish:
+		total += float(f[key])
+	var roll := rng.randf() * total
+	for f in fish:
+		roll -= float(f[key])
+		if roll <= 0.0:
+			return f.id
+	return fish[-1].id if not fish.is_empty() else ""
 
 func step(dt: float) -> void:
 	_t += dt
@@ -86,14 +102,24 @@ func step(dt: float) -> void:
 			velocity.y -= 9.8 * dt
 			var p := global_position + velocity * dt
 			var ground: float = terrain.sample_height(p.x, p.z)
-			if p.y <= terrain.water_level and ground < terrain.water_level - MIN_DEPTH:
+			var water: Dictionary = world.water_at(p.x, p.z)
-				p.y = terrain.water_level
+			if not water.is_empty() and p.y <= float(water.surface):
+				p.y = water.surface
+				water_type = water.type
+				table = ItemDB.water_fishing(water_type)
+				if table.is_empty() or table.fish.is_empty():
+					state = "landed"
+					Actions.notify.emit("Nothing to catch here")
+				elif float(water.depth) < float(table.min_depth):
+					state = "landed"
+					Actions.notify.emit("Too shallow here: cast further out")
+				else:
 					state = "floating"
 					wait_left = _next_wait()
 			elif p.y <= ground + 0.03:
 				p.y = ground + 0.03
 				state = "landed"
-				Actions.notify.emit("Cast into the water (deeper than this)" if ground < terrain.water_level else "Cast into the water")
+				Actions.notify.emit("Cast into the water")
 			global_position = p
 		"floating":
 			wait_left -= dt
@@ -110,7 +136,7 @@ func step(dt: float) -> void:
 			if bite_left <= 0.0:
 				state = "floating"
 				fish = ""
-				wait_left = _next_wait() * 1.3
+				wait_left = _next_wait() * float(ItemDB.fishing.modifiers.get("missed_wait", 1.3))
 				_mesh.position.y = 0.0
 				Actions.notify.emit("It got away")
 

scripts/world/world.gd

@@ -487,6 +487,17 @@ func _update_grass_cuts() -> void:
 			xfs.append(p.global_transform)
 	props.set_grass_cuts(xfs, 1.02)
 
+## What water is at (x, z): {"type": "lake"|"sea", "surface": y, "depth": m},
+## or {} on dry land. The one place that knows this island's water bodies, so
+## fishing (and later swimming, boats) work on any world that answers it.
+func water_at(x: float, z: float) -> Dictionary:
+	var ground: float = terrain.sample_height(x, z)
+	if terrain.inside_boundary(x, z, -2.0) and ground < terrain.water_level:
+		return {"type": "lake", "surface": terrain.water_level, "depth": terrain.water_level - ground}
+	if terrain.sea_weight(x, z) > 0.5 and ground < terrain.sea_level:
+		return {"type": "sea", "surface": terrain.sea_level, "depth": terrain.sea_level - ground}
+	return {}
+
 ## Leaves `count` of an item lying in the world at `xf` (an arrow stuck in a
 ## tree, a thrown spear, meat that didn't fit). Saved with the world.
 func drop_item(id: String, count: int, xf: Transform3D) -> Node3D:

tests/test_fishing_diet.gd

@@ -107,6 +107,19 @@ func _body(world: Node3D) -> void:
 	var inland := shore + Vector3(12, 0, 0)
 	inland.y = terrain.sample_height(inland.x, inland.z)
 
+	print("water and fish data")
+	var wl: Dictionary = world.water_at(lake.x, lake.y)
+	check(wl.get("type", "") == "lake" and wl.depth > 2.0, "the middle of the lake is deep lake water (%s)" % [wl])
+	check(world.water_at(shore.x + 3.0, shore.z).is_empty(), "the shore is dry land")
+	var sp: Vector2 = terrain.coast_point(terrain.sea_angle_deg, 40.0)
+	check(world.water_at(sp.x, sp.y).get("type", "") == "sea", "out past the cliffs is the sea")
+	var lt: Dictionary = DB.water_fishing("lake")
+	var ids := []
+	for f in lt.get("fish", []):
+		ids.append(f.id)
+	check(ids == ["perch", "trout"] and lt.min_depth == 0.5, "the lake's fish come from data/fish.json (%s)" % [ids])
+	check(DB.water_fishing("sea").is_empty(), "this island has no sea fish defined (the cliffs are in the way)")
+
 	print("casting")
 	sv.stamina = 100.0
 	check(_cast(world, player, out) and world.bobber != null, "cast the line")