From 8e8f10eb960e59d404f50f918b57bfe2107f0240 Mon Sep 17 00:00:00 2001 From: Paul Bailey Date: Wed, 4 Nov 2026 18:17:26 +0000 Subject: [PATCH] Tutorial world plan (docs/TUTORIAL_DESIGN.md), roadmap updated --- docs/ROADMAP.md | 9 ++- docs/TUTORIAL_DESIGN.md | 167 +++++++++++++++++++++++++++++++++++++++ docs/WORLDLETS_DESIGN.md | 1 + 3 files changed, 175 insertions(+), 2 deletions(-) create mode 100644 docs/TUTORIAL_DESIGN.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 794f8b2..1f88e85 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -36,6 +36,10 @@ Detailed plan in `docs/SURVIVAL_DESIGN.md` (phases M1a–M1d). - [x] Wolves at night with a den and a 3-day grace period, wolf cloak *(M1e)* - [x] Fishing (rod, perch and trout, grilling) and a mixed diet *(M1e)* - [ ] Hide armour, more recipes, sea fishing *(later M1 polish)* +- [x] Wild flax (fibre plants) *(polish)* +- [ ] **Tutorial world**: a guided first island that teaches gathering, + crafting, chopping, food and the mixed diet, hunting, fishing, + shelter and the night *(phases T1-T4, `docs/TUTORIAL_DESIGN.md`)* - **Done when:** gather → craft → build a tiny shelter, single-player. ## M2 — Multiplayer · ~2–4 months @@ -46,8 +50,9 @@ phases M2.0-M2.7). - [ ] Refactor state to server-authoritative (single-player becomes loopback server) - [x] Headless dedicated server, joining, identity handshake, names, player list *(M2.1)* - [x] ENet transport, player bodies and name tags, local movement checked by the server, interpolation for others *(M2.2)* -- [ ] Replicate resource nodes, inventory, building, health -- [ ] Persistence: world save/load on the server +- [x] Replicate resource nodes, pickups, building, chests, fires, doors, clock *(M2.3)* +- [x] Persistence: world save/load on the server *(M2.3)* +- [ ] Per-player inventory, stats and saves on the server *(M2.4)* - **Done when:** a friend joins your self-hosted server and you build together. ## M3 — Addon SDK + sandbox · ~2–3 months diff --git a/docs/TUTORIAL_DESIGN.md b/docs/TUTORIAL_DESIGN.md new file mode 100644 index 0000000..dab6a27 --- /dev/null +++ b/docs/TUTORIAL_DESIGN.md @@ -0,0 +1,167 @@ +# Tutorial world design + +Status: **proposal**. Nothing here is built yet. + +A short, guided first world that teaches the survival loop by having you +do it: gather, craft, chop, eat, hunt, cook, fish, keep a mixed diet, +build a shelter and get through a night. It uses the real game systems +(Actions, crafting, creatures, diet), so what you learn is exactly how the +real game behaves, and nothing in it can drift out of date. + +## 1. What the player sees +- The title screen gets **Tutorial** (above New World). The first time the + game starts with no worlds, it suggests it: "New here? Try the tutorial + (about 20 minutes)". +- You wake on a small, calm island (the **Tutorial worldlet**, §4) on a + clear morning. A short path loops round it past a few marked spots. +- A **guide panel** (top right, under the clock) shows the current step: a + title, one or two lines of how, and a progress count ("Sticks 2/3"). + A soft **marker** (a pale glowing post or a ring on the ground, plus an + arrow at the screen edge when it's off-screen) shows where to go. +- When a step is done: a tick, a short sound, and the next step slides in. + `H` hides the panel; the pause menu has **Skip step** and **Leave + tutorial**. +- Nothing is forced. You can wander off, do steps early (they tick + straight away) or ignore them. The panel only waits for the thing it + asked for. + +## 2. The steps +Grouped into chapters. Each step completes on a real game event, never on +a timer. Numbers below match today's recipes and items. + +**1. First tools** +1. *Look around.* Move with WASD, look with the mouse. (Done: walked 10 m.) +2. *Pick up 3 sticks and 3 stones.* "Look at one and press E." Marker on a + cluster by the path. +3. *Pick wild flax.* "The pale tall plants give fibre, for torches, bows + and beds." +4. *Open your inventory (Tab) and craft a Stone Axe.* Highlights the recipe. +5. *Put the axe in your hand* (1-8 or the hotbar) *and chop a tree.* "Hold + LMB at the trunk. Trees give wood, and sticks when they fall." +6. *Craft a Stone Pickaxe and break a boulder* for stone and flint. + +**2. Fire and food** +7. *Build a campfire* (place with LMB, rotate with R). "Fire gives light + and warmth, and you cook on it. Feed it wood or sticks with E." +8. *Pick berries* from a bush, then *eat some* (RMB with them in hand). +9. *Find mushrooms* under the trees. "Raw is fine, roasted at the fire is + much better." Roast one. +10. **The diet.** The panel points at the HUD's three Diet bars: Meat, + Fish, Greens. "Each food fills one. Keep all three up: let one run low + and you stop healing; two, and you start starving even on a full + stomach. All three high: you heal faster." Done when you've read it + (Continue). + +**3. Hunting** +11. *Craft a Wooden Club*, or a Spear at a workbench (build a workbench + first: "most tools and weapons need one nearby"). +12. *Hunt a rabbit.* The tutorial island has a fenced meadow with rabbits + that stay nearby. "Rabbits bolt if you sprint at them. Walk up close." +13. *Butcher it* (E on the carcass) *and cook the meat at the fire.* + "Raw meat hurts you. Cooked meat heals and makes you Well fed." +14. *(Optional, shown as a tip)* Deer outrun you (use a bow); boars are + calm until you hit one, then they charge. The panel shows each animal + with a small picture: what it drops and how to take it. + +**4. Fishing** +15. *Craft a Fishing Rod* (2 sticks, 3 fibre, 1 flint at the workbench). +16. *Catch a fish* from the pond. "Cast with LMB. When the float dips, + click within a second and a half." Grill it. Fish bar fills. + +**5. Shelter and night** +17. *Build a small hut*: 4 floors, walls, a door and a roof. A ghost + outline shows where (you can build anywhere, the outline is a + suggestion). "Pieces need support: walls on floors, roofs on walls." +18. *Craft a bed, place it inside and set your spawn* (E). +19. **Night.** The clock jumps to dusk. "It gets cold and dark. Stay by a + fire, carry a torch, or get inside." Craft a torch. +20. **Wolves** (from a safe distance). One wolf appears at the edge of the + firelight and circles. "Wolves come out from night 4 in a real world. + They won't come close to a lit fire, a torch makes them hesitate, and + they can't bite through walls." It slinks off. (A scripted wolf: it + never attacks in the tutorial.) +21. *Sleep in your bed until morning.* "You can only sleep at night, under + a roof, with walls round you, and not with wolves about." + +**Finish.** A summary card: what you learned, plus a reminder of the +shortcuts (E, Tab, X to dismantle, R to rotate, RMB to eat or wear), then +**Start your own world** (to New World) or **Keep exploring** (stays on the +tutorial island). + +Also covered as short tips when they first become relevant, in the +tutorial and later in real worlds (§5): getting wet and cold in rain, +death and your grave, stamina, carcasses rotting, regrowth, dismantling. + +## 3. How it works (code) +- **`data/tutorial.json`**: the steps as data. Each has an id, chapter, + title, text, an optional marker ("near": a named spot), an optional + set-up (give an item, set the time, spawn the wolf) and a **goal**: an + event plus a count. + ```json + {"id": "sticks", "title": "Gather sticks and stones", + "text": "Look at one and press E.", + "marker": "start_pickups", + "goal": {"all": [{"gained": "stick", "count": 3}, {"gained": "stone", "count": 3}]}} + ``` +- **Goal events** come from what already exists: `Actions.item_gained`, + crafting, placing a piece, `Actions.notify`-level events, a creature's + death, a carcass butchered, eating (by food group), a fish caught, + sleeping, walking a distance. A small **`Guide` autoload** listens to + those, checks the current step's goal and moves on. Adding a few signals + to Actions (`crafted`, `placed`, `ate`, `killed`, `caught`, `slept`) is + the main engine change, and they're useful for addons (M3) too. +- **The guide panel and marker** are UI only (`scripts/ui/guide.gd`). +- **Progress is saved** in the tutorial world's save (current step, done + steps), so you can quit and come back. +- **Scripted bits** are a handful of small hooks, not a scripting language: + set the time, spawn a calm creature group in a fenced area, spawn the + "demo wolf" (a wolf in a state that circles and leaves), show a ghost + outline for the hut. + +## 4. The tutorial island +A **worldlet** (docs/WORLDLETS_DESIGN.md), about 160 m across, with a +fixed seed, so everyone gets the same island: +- small and calm: one pond (for fishing), a stand of trees, a few + boulders, berry bushes and mushrooms along the path, flax by the pond; +- a fenced rabbit meadow; no wolves except the scripted one; deer and a + boar further off for the optional tip; +- **named spots** ("start_pickups", "first_tree", "pond", "hut_site"...) + that the steps' markers point at; +- the clock starts at 08:00, clear weather, and the wolf grace rules are + replaced by the script. + +Until the worldlet work is done (W0-W2), a **first version** can run on +the normal Valley island with a fixed seed (a sheltered spot near the +spawn as the tutorial area), with markers placed by searching for the +nearest tree, bush, boulder and so on. Everything in §3 carries over +unchanged when the proper tutorial island arrives. + +## 5. Hints in real worlds (optional, same system) +The same Guide can run **light hints** in normal worlds, off by default +for experienced players and on for anyone who finished or skipped the +tutorial: one-off tips the first time something happens (first rain, first +night, the Day 3 howl, a low diet bar, first death). A setting turns them +off. + +## 6. Multiplayer +The tutorial is **single-player only** (it's your own world). Hints in +real worlds work online too, since they only listen to your own events. + +## 7. Phases and tests +| Phase | Delivers | Done when | +|---|---|---| +| **T1** | Actions events (`crafted`, `placed`, `ate`, `killed`, `caught`, `slept`), the Guide autoload, `data/tutorial.json`, the guide panel and markers | a headless test plays the first chapter by calling Actions and every step ticks in order | +| **T2** | the whole tutorial on the Valley island (fixed seed): all chapters, scripted night and demo wolf, title-screen entry, saved progress | a headless bot completes every step; screenshots of each chapter | +| **T3** | the tutorial island worldlet (after W0-W2) with the fenced meadow and named spots | the same bot completes it there, and the shared suites pass on it | +| **T4** | hints in real worlds, with a setting | each hint fires once, on the right event | + +T1-T2 don't depend on anything else and could come before or after M2.4. + +## 8. Questions for you +1. **Length:** roughly 20 minutes for everything above. Shorter (just + chapters 1-2, the rest as hints), or is full-length right? +2. **Tone of the text:** plain and friendly (as written), or with a bit of + character, like an old hermit who lives on the island and talks you + through it? +3. **Before or after the rest of M2?** My suggestion: after M2.4, so the + tutorial teaches the game as it'll be when you play with friends. diff --git a/docs/WORLDLETS_DESIGN.md b/docs/WORLDLETS_DESIGN.md index 4bd07e6..e79d548 100644 --- a/docs/WORLDLETS_DESIGN.md +++ b/docs/WORLDLETS_DESIGN.md @@ -16,6 +16,7 @@ in seed: | **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 | +| **Tutorial** | small (~160 m), calm, fixed seed | one pond | guided steps, a fenced rabbit meadow, named spots (docs/TUTORIAL_DESIGN.md) | 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,