In-Game Tutorial System

Relevant source files

The following files were used as context for generating this wiki page:

• src/screens/HelpScreen.ts
• src/store/MiscStore.ts
• src/screens/StartScreen.ts
• src/components/instructions/Instructions1.ts
• src/components/instructions/Instructions2.ts
• src/components/instructions/Instructions3.ts
• src/components/instructions/Instructions7.ts
• src/components/instructions/Instructions10.ts
• src/Game.ts

The In-Game Tutorial System is a multi-page, interactive guide designed to teach players the core mechanics of Farm Siege. It is implemented as a dedicated screen (HelpScreen) that can be triggered in two ways: automatically before the first game for a new player, or manually via the "Help" button on the main menu. The system uses a series of distinct, animated components to demonstrate actions like moving, planting, harvesting, and fighting enemies.

The tutorial's state, including the current page and its operational mode, is managed by the MiscStore. This ensures a clear separation of concerns and allows different parts of the application, like the StartScreen and HelpScreen, to react to and control the tutorial's flow.

Sources: src/screens/HelpScreen.ts, src/screens/StartScreen.ts:40-59, src/store/MiscStore.ts:10-12

Architecture and Core Components

The tutorial system is built around three main architectural pieces: a screen container (HelpScreen), a state manager (MiscStore), and a collection of individual instruction page components (Instructions1 through Instructions10).

Sources: src/screens/HelpScreen.ts, src/store/MiscStore.ts

HelpScreen Container

The HelpScreen.ts class is the central component that orchestrates the tutorial. It acts as a container that displays a dialog box and renders the appropriate instruction page based on the current state. It is responsible for:

• Displaying a consistent UI frame, including a "HOW TO PLAY" title and navigation buttons.
• Managing pagination logic through goBack() and continue() methods.
• Conditionally rendering one of the ten InstructionsX components based on the currentPage value from MiscStore.
• Changing button sprites based on the page number (e.g., showing a "Home" icon on the first page and a "Play" icon on the last page when in beforeGame mode).

Sources: src/screens/HelpScreen.ts:38-66, 76-135

The following diagram illustrates the component hierarchy within the HelpScreen.

MiscStore State Management

The MiscStore is a global state container that holds all data related to the tutorial's status. This decouples the state from the UI components, allowing different screens to interact with the tutorial flow.

Key properties in MiscStoreContent:

Property	Type	Description
instructionsPage	number	The current page number of the tutorial being displayed (1-10). Default is 1.
instructionsMode	'manual' | 'beforeGame'	Defines the context in which the tutorial was opened. manual is from the main menu, beforeGame is for new players.

The store provides methods to manipulate this state:

• changeInstructionsPage(newPage: number): Updates the instructionsPage.
• setInstructionsMode(newMode: ...): Sets the current mode.
• resetInstructions(): Resets instructionsPage to 1.

Sources: src/store/MiscStore.ts:10-12, 31-52

The diagram below shows the two possible states for the tutorial's mode.

InstructionsX Components

Each page of the tutorial is a self-contained Component (e.g., Instructions1, Instructions2). These components are responsible for displaying a short instructional text and a looping animation that demonstrates a specific game mechanic.

Common characteristics:

• They extend the base Component class.
• They use an internal timer and an onTick method to drive their animations.
• The template array defines the visual elements: Text for the instruction and other components like Character, Tomato, Rabbit, and input button sprites to create the animation.
• Conditional rendering (show property) is used to time the appearance and disappearance of animated elements.

For example, Instructions2.ts demonstrates how to plant crops.

// src/components/instructions/Instructions2.ts:16-26
export default class Instructions2 extends Component<Instructions2Props> {
  private timer = 0;

  onTick(_ctx: PropsContext<Instructions2>, timeDifference: number): void {
    this.timer += timeDifference;
  }

  private get showPlant(): boolean {
    const time = this.timer % 2000;
    return time > 1000;
  }
  // ...
}

This snippet shows the timer-based logic used to control the animation, where showPlant becomes true during a specific interval of the 2-second loop.

Sources: src/components/instructions/Instructions2.ts:16-26, src/components/instructions/Instructions3.ts:19-29, src/components/instructions/Instructions7.ts:20-35

Tutorial Flow

The tutorial can be initiated from the StartScreen in two different scenarios.

Entry Points

1. Automatic (First-Time Player): When a player clicks "Play" for the first time, the startGame method in StartScreen checks for a helpShown cookie. If the cookie is not present, it sets the instructionsMode to 'beforeGame' and navigates to the HelpScreen. Upon completion, it starts the game.
2. Manual: A player can click the "Help" button on the StartScreen at any time. This calls the showHelp method, which sets the instructionsMode to 'manual' and navigates to the HelpScreen. Upon exiting, the player is returned to the StartScreen.

Sources: src/screens/StartScreen.ts:40-59, 78-91

This flow is visualized in the diagram below.

Navigation and State Transitions

Navigation within the HelpScreen is handled by the goBack() and continue() methods, which increment or decrement the instructionsPage in the MiscStore.

The following sequence diagram shows the interactions when a new player starts the game.

Tutorial Pages Overview

There are a total of 10 instruction pages, each covering a specific aspect of the gameplay.

Page	Component	Description
1	Instructions1	How to move the character using WASD/Arrow Keys or a gamepad.
2	Instructions2	How to plant crops using the 'V' key or 'A' button.
3	Instructions3	How to harvest fully grown crops for points.
4	Instructions4	Explains that only fully grown plants award points.
5	Instructions5	Introduces the various threats: lightning, moles, and rabbits.
6	Instructions6	How to smash moles with the hammer.
7	Instructions7	How to shoot rabbits with the gun.
8	Instructions8	How to remove weeds with the shovel.
9	Instructions9	Explains that lightning strikes cannot be prevented.
10	Instructions10	Final summary: protect plants, get points, game ends when no plants are left.

Sources: src/screens/HelpScreen.ts:91-130, src/components/instructions/Instructions1.ts, src/components/instructions/Instructions2.ts, src/components/instructions/Instructions3.ts, src/components/instructions/Instructions4.ts, src/components/instructions/Instructions5.ts, src/components/instructions/Instructions6.ts, src/components/instructions/Instructions7.ts, src/components/instructions/Instructions8.ts, src/components/instructions/Instructions9.ts, src/components/instructions/Instructions10.ts

Summary

The In-Game Tutorial System is a modular and state-driven feature that effectively onboards new players. By separating the container (HelpScreen), state (MiscStore), and content (InstructionsX components), the system is easy to manage and extend. Its ability to run in different modes (beforeGame vs. manual) provides flexibility for both first-time players and those seeking a refresher on the game's rules.

Sources: src/screens/HelpScreen.ts, src/screens/StartScreen.ts, src/store/MiscStore.ts