238 lines
13 KiB
Markdown
238 lines
13 KiB
Markdown
# Tutorial world design
|
|
|
|
Status: **T1, T2 and T4 built**: the whole tutorial, on the Valley island
|
|
(seed 1337), with Old Tam the hermit, and his tips in normal worlds. T3
|
|
(its own island) waits for the worldlets.
|
|
|
|
*As built in T4:*
|
|
- 16 tips in data/hints.json, in Old Tam's voice: soaked, cold, freezing,
|
|
hungry, a poor diet, food poisoning, food gone rotten, nightfall, the
|
|
wolves' howl, the red moon, a hard winter, snow, a storm, out of
|
|
breath, a first proper shelter, and back on your feet after dying.
|
|
- The `Hints` autoload (scripts/core/hints.gd) checks your own survival
|
|
statuses, the weather, the clock and your bag, plus two events (a howl,
|
|
a death), so tips work the same online (the server mirrors statuses).
|
|
Each shows once per player (user://hints.json), in list order, 16 s
|
|
apart, never while you're dead, and not in the tutorial world or on a
|
|
server.
|
|
- A card top right (scripts/ui/hint_card.gd) for 14 s; H puts it away.
|
|
Pause menu: **Old Tam's tips** on/off and **Show again**. On by default.
|
|
- tests/test_hints.gd. Headless runs never start tips unless a test asks
|
|
(so the suites can't use up your real ones).
|
|
|
|
*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**
|
|
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. *On hold until the worldlet work starts (Paul, Nov 5).* | 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.
|