Getting Started

Prerequisites

To get started writing your story using the provided console application, you will need:

A text editor for writing your story.
A copy of the ZodiacsTextEngine console application, ZodiacsTextConsole.

If you intend to integrate the engine into another environment, you'll also need:

An IDE capable of creating .NET applications, such as Visual Studio, Visual Studio Code, or JetBrains Rider.
The ZodiacsTextEngine package.
A .NET project to integrate the ZodiacsTextEngine into.

Download

The console application and the engine DLL can be downloaded from the releases page on GitHub.

For more information how to setup the engine in a .NET project, refer to Using ZodiacsTextEngine in a custom Application.

Using ZodiacsTextConsole

The ZodiacsTextConsole is a pre-built console application that allows you to load and play ZodiacsTextEngine stories with ease.

There are two ways in which ZodiacsTextConsole can be used:

Directly loading a story and starting it.
Launching the main menu to select a story to play.

Both methods additionally support the --debug command line argument to launch the text engine in debug mode, printing additional debug information about the story being played.

Direct Loading

To load a story, the executable can be run with the --content command line argument, followed by the path to the story, which can be either a directory or a zip file.

File paths can be either absolute or relative relative to the executable.

Example: ZodiacsTextConsole.exe --content "C:/Path/To/Your/Story/content"

Main Menu

To launch the main menu, the executable needs to be run with the --menu command line argument.

The main menu will list all available stories placed in the stories subdirectory below the executable.

Writing Stories

Room Files

The ZodiacsTextEngine follows a file structure where each section is defined in its own file (called a room). The engine runs through the content of a room file sequentially, executing effects and displaying text until the end, where it awaits user input. Depending on user input, the story can branch into different rooms, execute other effects (e.g. adding an item to the player's inventory), or simply provide flavor text.

By default, the engine uses a file named start.room as the starting point for the story.

See Room File Structure for detailed information on how to write room files.

Story Metadata

The story.meta file is an optional file that contains metadata about the story. It expects the following format:

Title=Story Title Authors=Author Name 1,Author Name 2, ... Version=1.0 Description=A brief description of the story.

All lines are optional, but it is recommended to provide at least the title for displaying purposes.

Example File Structure

The folder structure for a story may look like this:

Game Directory

game.exe

content

story.meta

start.room

entrance.room

hallway.room

dungeon

dungeon_entrance.room

dungeon_trap.room

custom_functions.funcs

...

The required file structure and name of the start room can be customized when writing a custom application.

Room files can be grouped into subfolders without restrictions, the subfolders have no effect on how the room files are processed.