Tutorial world design

Status: T1 and T2 built: the whole tutorial, on the Valley island (seed 1337), with Old Tam the hermit. T3 (its own island) and T4 (hints in real worlds) are proposals.

As built in T2:

All five chapters, 22 steps (data/tutorial.json), in Old Tam's voice: first tools; fire and food (campfire, berries, a roasted mushroom, the diet bars); hunting (workbench, a weapon, a rabbit, butcher and cook, a tip about the other animals); fishing (rod, a catch, grilled); shelter and night (a hut you can stand inside, a bed and spawn, nightfall and a torch, the demo wolf, sleeping).
More goals: any (club or spear, perch or trout), shelter, bed_spawn, demo_wolf, continue (Enter on the reading steps).
Step set-ups: the clock jumps to dusk (18:36) and to bedtime (21:00); three rabbits appear 14 m off for the hunt; the demo wolf (scripts/creatures/tutorial_wolf.gd) circles at 11 m for 18 s and slinks off, never biting.
Markers for berry bushes, rabbits, the carcass, the lake shore.
The tutorial island is calm: no wolf pack, no bear, no thieves.
Title screen: Tutorial above New World (it says "carry on" once started; with no worlds yet: "New here? Try the tutorial"). Pause menu: Skip this step, Leave the tutorial (saved, carry on later).
The end: Old Tam's goodbye card, Start your own world (to the New World page) or Keep exploring.
tests/test_tutorial_full.gd: a bot plays all 22 steps through Actions, in order, to the card. (Bulk materials, like a hut's wood, go straight into its bag; every goal is done as a player does it.)
The hut outline (§2 step 17): Old Tam marks out a 20-piece hut, pale as a ghost, on the first clear flat spot 5 m or more from your fire (scripts/ui/hut_outline.gd). A piece held within 2 m of its matching ghost snaps right into it; each ghost fades as it's filled, and the marker points at the outline. Building elsewhere still counts. The outline goes when the step ends or the tutorial is left.
Not yet: sounds for the tick.

As built in T1:

Actions has signals for what players do: crafted, harvested (with whether it fell), placed, ate, killed, butchered, caught, slept (plus the old item_gained).
The Guide autoload (scripts/core/guide.gd) runs data/tutorial.json: goals walk, gained, crafted, felled, placed, ate, killed, butchered, caught, slept, continue, and all of several. It counts from the tutorial's start, so a step done early ticks the moment it comes up. Markers: the nearest pickup of a kind, tree or boulder, hidden once you have what it's for (unless_have).
The guide panel (scripts/ui/guide.gd) under the clock: chapter, step n of m, title, how, and a count ("Sticks 2/3 · Stone 0/3"); a tick when a step's done; H hides it. The marker is a pale glowing post and ring, with an arrow and distance at the screen edge when it's off-screen.
A world with "tutorial": true in its meta.json runs it (the title screen entry comes in T2); -- --tutorial runs it on any world for now. Progress is saved with the world.
Chapter 1 (First tools) is in the data; chapters 2-5 come with T2. The guide is Old Tam, the island's hermit (decided): the steps are in his voice, with his name on the panel.

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

Look around. Move with WASD, look with the mouse. (Done: walked 10 m.)
Pick up 3 sticks and 3 stones. "Look at one and press E." Marker on a cluster by the path.
Pick wild flax. "The pale tall plants give fibre, for torches, bows and beds."
Open your inventory (Tab) and craft a Stone Axe. Highlights the recipe.
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."
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.

{"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

Length: roughly 20 minutes for everything above. Shorter (just chapters 1-2, the rest as hints), or is full-length right?
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?
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.

12 KiB Raw Blame History