TypeScript Tutorial: Building a Simple Interactive Story Game

Written by

learnmodernjavascript

in

Have you ever wanted to create your own interactive story, where the reader’s choices shape the narrative? Perhaps you’ve dabbled in text-based adventure games or envisioned branching narratives like those found in “Choose Your Own Adventure” books. Building such a game can seem daunting, but with TypeScript, we can create a simple yet engaging interactive story experience that is both fun to build and easy to understand. This tutorial will guide you through the process, providing clear explanations, step-by-step instructions, and practical code examples. We’ll focus on the core concepts, making it accessible even if you’re new to TypeScript.

Why TypeScript for Interactive Stories?

TypeScript brings several advantages to this project. First, its static typing helps catch errors early, preventing runtime surprises. Second, TypeScript’s object-oriented features allow us to structure the game logically, making it easier to maintain and extend. Finally, the tooling around TypeScript, including excellent IDE support, makes the development process more efficient and enjoyable.

Setting Up Your Environment

Before we dive into the code, let’s set up our development environment. You’ll need:

  • Node.js and npm (Node Package Manager) installed on your system.
  • A code editor (Visual Studio Code, Sublime Text, or similar) with TypeScript support.

Once you have these prerequisites, create a new project directory and initialize it with npm:

mkdir interactive-story
cd interactive-story
npm init -y

Next, install TypeScript globally or locally (we’ll use a local installation here):

npm install typescript --save-dev

Now, create a `tsconfig.json` file in your project root. This file configures the TypeScript compiler. You can generate a basic one using the TypeScript compiler itself:

npx tsc --init

This will create a `tsconfig.json` file. You can customize this file to fit your project’s needs. For our project, the default settings will suffice. Finally, create a `src` directory to hold our TypeScript files. Inside `src`, create a file named `story.ts`.

Core Concepts: Scenes, Choices, and the Story Engine

Our interactive story will be built around three core components: scenes, choices, and the story engine. Let’s define each of these:

  • Scenes: Each scene represents a point in the story. It contains text to be displayed to the user and a set of choices.
  • Choices: Each choice represents an action the user can take. It has text to display to the user and a reference to the next scene.
  • Story Engine: This is the central part of our game. It manages the current scene, handles user input, and navigates between scenes based on the user’s choices.

Implementing Scenes and Choices

Let’s start by defining the `Scene` and `Choice` classes in `src/story.ts`:

// src/story.ts

class Choice {
  text: string;
  nextSceneId: string;

  constructor(text: string, nextSceneId: string) {
    this.text = text;
    this.nextSceneId = nextSceneId;
  }
}

class Scene {
  id: string;
  text: string;
  choices: Choice[];

  constructor(id: string, text: string, choices: Choice[]) {
    this.id = id;
    this.text = text;
    this.choices = choices;
  }
}

In this code:

  • The `Choice` class has `text` (the text to display to the user) and `nextSceneId` (the ID of the next scene).
  • The `Scene` class has `id` (a unique identifier for the scene), `text` (the scene’s description), and `choices` (an array of `Choice` objects).

Creating the Story Engine

Now, let’s create the `StoryEngine` class to manage the game flow:

// src/story.ts (continued)

class StoryEngine {
  scenes: { [key: string]: Scene } = {}; // Use an object for efficient lookup
  currentSceneId: string | null = null;

  addScene(scene: Scene): void {
    this.scenes[scene.id] = scene;
  }

  start(sceneId: string): void {
    this.currentSceneId = sceneId;
    this.displayScene();
  }

  displayScene(): void {
    if (!this.currentSceneId) {
      console.log("Game Over!");
      return;
    }

    const currentScene = this.scenes[this.currentSceneId];

    if (!currentScene) {
      console.log("Scene not found!");
      return;
    }

    console.log(currentScene.text);
    if (currentScene.choices.length > 0) {
      currentScene.choices.forEach((choice, index) => {
        console.log(`${index + 1}. ${choice.text}`);
      });
      this.getUserChoice(currentScene);
    } else {
      console.log("The End.");
    }
  }

  getUserChoice(scene: Scene): void {
    const readline = require('readline').createInterface({
      input: process.stdin,
      output: process.stdout
    });

    readline.question('Choose your action: ', (choiceIndex: string) => {
      const index = parseInt(choiceIndex, 10) - 1;
      if (isNaN(index) || index = scene.choices.length) {
        console.log('Invalid choice. Please try again.');
        readline.close();
        this.displayScene();
        return;
      }

      const choice = scene.choices[index];
      this.currentSceneId = choice.nextSceneId;
      readline.close();
      this.displayScene();
    });
  }
}

In the `StoryEngine` class:

  • `scenes`: This property stores all the scenes in the story, using an object for efficient lookup by scene ID.
  • `currentSceneId`: Stores the ID of the scene currently being displayed.
  • `addScene(scene: Scene)`: Adds a scene to the story.
  • `start(sceneId: string)`: Starts the story at the given `sceneId`.
  • `displayScene()`: Displays the current scene’s text and choices. It also handles the “Game Over” and “Scene not found” scenarios.
  • `getUserChoice(scene: Scene)`: Uses the `readline` module to get the user’s choice from the console. It validates the input and navigates to the next scene based on the chosen option.

Building Your Story

Now, let’s create a simple story:

// src/story.ts (continued)

// Create scenes
const scene1 = new Scene(
  'start',
  'You wake up in a dark forest. You see a path to the north and a path to the east.',
  [
    new Choice('Go north', 'northPath'),
    new Choice('Go east', 'eastPath'),
  ]
);

const northPath = new Scene(
  'northPath',
  'You follow the path north and find a hidden treasure chest.',
  [] // No choices - end of this path
);

const eastPath = new Scene(
  'eastPath',
  'You walk east and encounter a ferocious wolf. You can run or fight.',
  [
    new Choice('Run away', 'runAway'),
    new Choice('Fight the wolf', 'fightWolf'),
  ]
);

const runAway = new Scene(
  'runAway',
  'You successfully escape the wolf and find a village.',
  [] // End of this path
);

const fightWolf = new Scene(
  'fightWolf',
  'You bravely fight the wolf, but it's too strong. You are defeated.',
  [] // End of this path
);

Then, create the story engine and add the scenes:

// src/story.ts (continued)

// Create the story engine
const storyEngine = new StoryEngine();
storyEngine.addScene(scene1);
storyEngine.addScene(northPath);
storyEngine.addScene(eastPath);
storyEngine.addScene(runAway);
storyEngine.addScene(fightWolf);

// Start the story
storyEngine.start('start');

Running the Game

To run your game, compile the TypeScript code and then execute the JavaScript file. Create a `tsconfig.json` file in your project root, if you have not already. Then, run the following commands:

tsc
node ./src/story.js

You should see the first scene displayed in your console, along with the choices. Enter the number corresponding to your choice, and the story will progress accordingly.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid or fix them:

  • Incorrect Scene IDs: Typos in scene IDs are a common cause of “Scene not found” errors. Double-check your IDs for consistency.
  • Invalid Choice Indices: Ensure that the user’s input is within the valid range of choices. Use input validation, as demonstrated in the `getUserChoice` function, to prevent errors.
  • Missing `nextSceneId`: If a choice doesn’t lead anywhere, you’ll get stuck. Make sure each choice has a `nextSceneId` that points to a valid scene.
  • Forgetting to Add Scenes: You must add all scenes to the `storyEngine` using the `addScene()` method, or they won’t be accessible.
  • Asynchronous Operations: The `readline.question` method is asynchronous. Make sure you handle the user’s choice properly within the callback function to avoid unexpected behavior.

Enhancements and Next Steps

This is a basic framework. Here are some ways to extend your interactive story:

  • Add more complex choices: Include multiple levels of choices and branching.
  • Implement character stats: Add health, inventory, and other attributes to influence the story.
  • Introduce conditional choices: Make choices depend on the player’s stats or previous actions.
  • Add graphics: Integrate images or a simple UI to enhance the user experience.
  • Save and load games: Allow players to save their progress and resume later.
  • Create a more sophisticated UI: Use a library like React, Angular, or Vue.js to build a web-based version with a graphical interface.

Summary / Key Takeaways

In this tutorial, we’ve built a simple interactive story game using TypeScript. We’ve covered the fundamental concepts of scenes, choices, and a story engine. We’ve also explored how to set up the development environment, structure the code using classes, and handle user input. By starting with a clear, organized structure, we made the project manageable and adaptable. Remember, the key to building engaging interactive stories is to focus on clear storytelling, well-defined choices, and a robust engine to manage the narrative flow. This project provides a solid foundation for more complex and creative interactive experiences.

FAQ

Q: How can I debug my game?

A: Use the `console.log()` statements to track the flow of your program, and inspect variables. Modern code editors, such as VS Code, have built-in debuggers that allow you to step through your code, set breakpoints, and inspect variables.

Q: How can I add more complex game mechanics?

A: You can add variables to track player stats (health, inventory, etc.), and use conditional statements to determine the outcome of choices based on these stats. You can also introduce functions to handle more complex actions, such as combat or puzzle-solving.

Q: Can I use this code for a web-based game?

A: Yes! The core logic can be adapted for a web-based game. You would need to replace the console input/output with HTML elements and event listeners.

Q: What are some good resources for learning more about TypeScript?

A: The official TypeScript documentation ([https://www.typescriptlang.org/](https://www.typescriptlang.org/)) is an excellent resource. There are also many online tutorials, courses, and books available on the subject.

Q: How can I handle errors more gracefully?

A: You can use `try…catch` blocks to handle potential errors, and provide informative error messages to the user. You can also implement input validation to prevent invalid input from causing problems.

This tutorial has provided a starting point for building your own interactive story game. With TypeScript, you have a powerful tool to create engaging and dynamic narratives. As you experiment with different features, consider how you can integrate the core concepts you’ve learned to build more complex and immersive game experiences, perhaps even adapting them to a web environment that allows for wider distribution and interaction. The possibilities are vast, limited only by your imagination and the code you write.

More posts