Skip to content

Auto Warz — Tutorial & Onboarding Design

Document Type: Design Document Version: 0.1 Last Updated: 2026-03-04 Vault destination: 01_Design Documents Parent Document: [01_Master GDD](<./01_Master GDD.md>) Related Documents: [09_UI-UX Design Document](<./09_UI-UX Design Document.md>) · [04_Factory & Resource System Design](<./04_Factory & Resource System Design.md>) Folder: 01_Design Documents

Table of Contents

Design Principles

  1. Tutorial runs inside the real game — no separate scene, no fake level. The player's first session IS the tutorial. Everything they build during the tutorial stays in their session.
  2. Guided but not locked — the player is shown what to do next via tooltips and highlights, but is never physically blocked from doing something else. They can ignore a step, explore, and the tutorial patiently waits.
  3. Skippable entirely — veterans can dismiss the tutorial on the first prompt and it never reappears that session.
  4. Resumable — if the player closes the game mid-tutorial, it resumes from the last completed step on next load.
  5. Genesis is the voice — all tutorial prompts come from Genesis. It keeps the fiction intact and introduces the companion relationship naturally.
  6. Teach by doing — every step requires the player to perform the action themselves. No cinematics, no passive watching. Genesis prompts → player acts → step completes.
  7. Stop at the right moment — the tutorial ends once the first production chain is running. Everything beyond that the player discovers through play.

Tutorial Structure

The tutorial is a linear step sequence overlaid on the normal game session. It triggers automatically on a new session if the player has never completed it before.

Each step consists of: - A Genesis prompt — short, conversational, in-world message from Genesis - A highlight — the relevant UI element or world object is pulsed/outlined - A completion condition — an action the player must take to advance - An optional tip bubble — extra context that auto-dismisses after a few seconds

The tutorial does not pause the simulation. If the player takes a long time on a step, the factory keeps ticking normally.

Skip & Resume

Skipping

On the very first tutorial prompt, a Skip Tutorial button appears in the bottom-right of the prompt panel. Pressing it: - Dismisses all tutorial UI immediately - Marks tutorial as completed in PlayerProfile — never shows again for this player - Shows a brief tooltip: "Tutorial skipped. Press H at any time for hints."

Resuming

If the session is saved and loaded mid-tutorial: - Tutorial resumes from the last completed step - The prompt reappears with a brief recap: "Welcome back. Let's continue where we left off."

Replaying

Players can replay the tutorial from the main menu → Settings → Gameplay → Reset Tutorial. This clears the completion flag and restarts from Step 1 on the next new session.

Step-by-Step Flow

Step 0 — Wake Up (Automatic, no action required)

Trigger: New session starts for the first time
Action: None — this step auto-advances after the camera pan completes

What happens: - Camera starts zoomed out, slowly zooms in to the crash site - Genesis floats into frame from the wreckage - Tutorial prompt appears

Genesis prompt:

"Systems online. I am Genesis — your construction unit. The ship is gone but we are not. We need to build, and fast. Let me show you how."

Skip Tutorial button appears here.

Step 1 — Open the Build Menu

Completion condition: Player opens the build menu (B or clicks the build menu bar)
Highlight: Build menu bar at bottom of screen pulses

Genesis prompt:

"First, open the build menu. Press B or click the bar at the bottom of the screen."

Tip: "The build menu is where every building, belt, and connector lives. You'll use it constantly."

Step 2 — Place a Mining Drill

Completion condition: Player places a Mining Drill ghost on a Metal Ore deposit
Highlight: Nearest Metal Ore deposit outlined in amber. Mining Drill card in build menu pulsed.

Genesis prompt:

"Select the Mining Drill from the Extraction tab and place it on that ore deposit. I'll handle the rest."

Tip: "Green means valid placement. Red means something is in the way. Press R to rotate before placing."

On placement: - Ghost appears at location - Genesis immediately flies to it and begins building - Progress fill visible on ghost

Genesis prompt (while building):

"Building now. Watch the ghost fill — that's me working."

Step 3 — Watch Genesis Build

Completion condition: Mining Drill construction completes
Action: None — player watches Genesis work

Genesis prompt (on complete):

"Done. The drill is running — it's pulling ore from the deposit. But ore sitting in a building isn't useful. We need to move it."

Step 4 — Place an Output Connector

Completion condition: Player places an IoConnector on the output face of the Mining Drill
Highlight: Output face of the Mining Drill pulsed amber. IoConnector card in build menu pulsed.

Genesis prompt:

"Before we run a belt, place a Connector on the drill's output face. Connectors control which direction resources flow in and out of buildings."

Tip: "The green face is the output side. Press R to rotate the connector to face outward before placing."

Step 5 — Place a Belt

Completion condition: Player places at least one Belt segment leading away from the IoConnector
Highlight: Output face of the IoConnector pulsed. Belt card in build menu pulsed.

Genesis prompt:

"Now draw a belt from the connector outward. Belts carry resources between buildings."

Tip: "Click and drag to place multiple belt segments in one go."

Step 6 — Place a Smelter

Completion condition: Player places a Smelter ghost at the end of the belt run
Highlight: Smelter card in build menu pulsed. End of belt run highlighted.

Genesis prompt:

"Place a Smelter at the end of that belt. It turns raw ore into Metal Plates — the foundation of everything we'll build."

Step 7 — Place an Input Connector

Completion condition: Player places an IoConnector on the input face of the Smelter
Highlight: Input face of the Smelter pulsed amber. IoConnector card pulsed.

Genesis prompt:

"Now place a Connector on the Smelter's input face — the blue one. The belt needs a connector to deliver into the building."

Tip: "Blue face = input, green face = output. Every building needs connectors wherever resources enter or leave."

Step 8 — Connect the Chain

Completion condition: Belt connects IoConnector output → Smelter IoConnector input AND Smelter completes construction
Highlight: Gap in belt highlighted if chain is broken

Genesis prompt (if gap in belt):

"There's a gap in the belt. Fill it in so the ore can reach the Smelter."

Genesis prompt (on Smelter complete):

"The chain is connected. Ore flows from the drill, through the connectors, along the belt, into the Smelter. Metal Plates are being produced."

Step 9 — Read the Inventory Tab

Completion condition: Player sees the Metal Plate quantity tick up in the right flap Inventory tab
Highlight: Metal Plate row in the right flap Inventory tab pulses when the first plate is produced

Genesis prompt:

"Watch the right panel. Metal Plates. Everything we build needs them, and that list is how you know whether you are making enough."

Tip: "The Inventory tab lists every resource with its quantity and net rate. Green means you are producing more than you are using."

No panel to open. The right flap is expanded by default ([17_HUD Panel Flap](<./17_HUD Panel Flap.md>) -> Expand / Collapse), so this step is about noticing a readout that is already on screen, not opening one. The full-screen Factory Overview (F) this step used to teach was removed in [09_UI-UX Design Document](<./09_UI-UX Design Document.md>) v0.6.

Step 10 — Place a Buffer Chest

Completion condition: Player places a Buffer Chest with an IoConnector connected to the Smelter output
Highlight: Buffer Chest card in build menu pulsed. Smelter output face highlighted.

Genesis prompt:

"Connect a Buffer Chest to the Smelter's output — don't forget the connector. It stores Metal Plates until other buildings need them."

Step 11 — Tutorial Complete

Trigger: Buffer Chest placed and connected
Action: None — tutorial ends here

Genesis prompt:

"That's the foundation — extract, connect, process, store. From here, the factory is yours to build. I'll keep working as long as you keep placing. Good luck, Commander."

What happens: - Tutorial overlay fades out - Full HUD unlocks (any locked elements during tutorial are now active) - Achievement unlocked: First Chain — "Built your first production chain." - PlayerProfile.tutorial_complete = true — tutorial never triggers again for this player

Tooltip & Prompt Design

Prompt Panel

  • Appears bottom-left of screen, above the build menu bar
  • Genesis avatar icon on the left (small, matches Genesis visual design)
  • Short text — maximum 2 sentences per prompt
  • Auto-advances only on completion condition — never times out and advances on its own
  • Player can click the prompt panel to re-read the current step at any time

Highlight System

  • Target UI elements: pulsing amber outline, 1.5s cycle
  • Target world objects: pulsing amber ring on ground around the object
  • Only one highlight active at a time — always points to the next required action

Tip Bubbles

  • Appear above the prompt panel
  • Smaller text, lighter colour
  • Auto-dismiss after 6 seconds
  • Can be clicked to dismiss early

Genesis as Tutorial Guide

All tutorial communication comes from Genesis directly — no separate tutorial narrator or UI character. This establishes the companion relationship from the very first moment.

Tone: - Practical and direct — Genesis is a working bot, not a chatty assistant - Slightly dry personality — competent, understated, occasionally wry - Never condescending — assumes the player is intelligent, just new - Brief — never more than 2 sentences per prompt - Pronouns: it/its — never "he" or "she" in any UI copy or tutorial text

Voice delivery: A mix of expressive beeps/chirps and short synthetic speech lines. Tutorial prompts are delivered as synthetic speech. Acknowledgement sounds (task complete, build start) are beeps/chirps.

Examples of good Genesis tutorial voice:

"That belt has a gap. Fix it." "The Smelter needs ore. Connect the belt to its input face — the blue one." "Good. The chain is running. This is how everything works."

Examples of bad Genesis tutorial voice:

"Amazing job! You placed your very first belt! You're doing so well!" ❌ "In order to complete the production chain, you will need to ensure that the conveyor belt system is properly connected to both the extraction building and the processing building." ❌

What the Tutorial Does NOT Cover

The tutorial deliberately stops after the first production chain. These systems are left for the player to discover:

  • Research tree
  • Power system
  • Plan mode and war mode
  • IoConnectors and pipe system
  • Modules
  • Vertical levels
  • Blueprints
  • Multiplayer

These are covered by the in-game hint system (press H) — a lightweight reference panel that explains any system the player hasn't encountered yet, unlocking hints progressively as the player interacts with new systems.

Design note: The hint system is a separate, lighter feature — not part of this document. It should be designed alongside M2.7 Basic HUD & UI.

Implementation Notes

Data

# PlayerProfile.gd — add these fields
@export var tutorial_complete: bool = false
@export var tutorial_step: int = 0  # last completed step index

TutorialManager (autoload)

# TutorialManager.gd
# Reads PlayerProfile.tutorial_complete on session start
# If false → begins tutorial from tutorial_step
# Listens for completion conditions via signals
# Advances step and saves PlayerProfile on each completion
# Exposes skip() and reset() methods

Completion Condition Signals

Each step listens for an existing game signal — no new systems needed:

Step Signal
1 UIManager.build_menu_opened
2 BuildingManager.building_ghost_placed(id: "mining_drill")
3 BuildingManager.building_constructed(id: "mining_drill")
4 BuildingManager.building_placed(id: "io_connector") — on output face of mining drill
5 BeltManager.belt_placed
6 BuildingManager.building_ghost_placed(id: "smelter")
7 BuildingManager.building_placed(id: "io_connector") — on input face of smelter
8 BuildingManager.building_constructed(id: "smelter")
9 ResourceManager.resource_produced(id: "metal_plate")
10 BuildingManager.building_constructed(id: "buffer_chest")

Milestone

Tutorial implementation is part of M2.7 — Basic HUD & UI. The TutorialManager autoload and step data should be built alongside the HUD work.

Revision History

Version Date Changes
0.1 2026-03-04 Initial document — guided style, skippable, overlay on real session. 9-step flow from crash landing through first production chain. Genesis as tutorial voice, tone guidelines, tooltip/prompt design, hint system noted as separate feature, implementation notes with signal map.
0.2 2026-08-29 Step 9 rewritten from Open the Resource Panel to Read the Inventory Tab. It taught pressing F for the Factory Overview, a screen removed in 09_UI-UX Design Document v0.6. Reframed rather than repointed: the right flap is expanded by default, so there is no panel to open. (OI-021)