Using ZodiacsTextEngine in a custom Application

The ZodiacsTextEngine provides a simple .NET API that lets you implement your own text interface to capture user inputs and render the output.

Installation

Depending on the type of application you're creating, there are various ways to install the ZodiacsTextEngine:

NuGet Package

To start using the Text Engine, install the ZodiacsTextEngine NuGet package.
Refer to the installation instructions to add the package to your project.

Unity Package

In case of a Unity game project, the ZodiacsTextEngine can be installed using the separate Unity Package.

Manual Installation

If both options are unavailable, you can still download the repository and copy the files from the ZodiacsTextEngine/source directory directly into your project.

Initializing the Text Engine

To initialize and start the ZodiacsTextEngine, simply call:

ITextInterface textInterface = new (Your ITextInterface implementation); ContentLoader loader = new StandardContentLoader(); //Or your own content loader bool debug = false; TextEngine.Initialize(textInterface, loader, debug); TextEngine.StartGame();

Implementing ITextInterface

To provide your own text interface, create a class that implements ZodiacsTextEngine.ITextInterface, then pass it as a parameter to the engine during initialization as mentioned above.

Members of ITextInterface

The ITextInterface requires an implementation of the following members:

void Initialize(bool debug)
Called when the text engine initializes.
void OnDebugInfo()
Called during initialization if debug mode is enabled.
void OnLoadError()
Called when the content loader has failed to load the game files.
void SetTitle(string title)
Called when the title (normally the window title) is changed via the +TITLE effect.
void Clear()
Called when the output should be cleared, often caused by +CLEAR_OUTPUT effects.
Task<string> ReadInput()
Called when user input is requested. Can be asynchronous.
Task<Choice> RequestChoice(Room room)
Called when a choice must be made by the player. The return value must not be null. In case the player makes an invalid choice or incorrect input, this function must continue requesting input from the player until a valid choice is made or the game is closed. Can be asynchronous.
void ListChoices(List<Choice> choices)
Called when all currently available choices should be listed to the player.
void Write(string text, bool lineBreak, bool wordWrap, Color? color = null, Color? background = null)
Called when text should be written to the output. The parameters are as follows:
- text: The text to write.
- lineBreak: If true, a line break should be added after the text.
- wordWrap: If true, the text should be word-wrapped according to the interface's width.
- color: Optional text color. If null, the color should be left as-is.
- background: Optional background color. If null, the background color should be left as-is.
void LineBreak()
Called when a line break should be added to the output.
void Header(string text)
Called when a header should be added to the output. The styling of headers is up to the implementing interface.
void Hint(string text)
Called when a hint should be displayed to the player. Hints are usually brief and provide additional context or guidance and are often displayed in a more muted color to distinguish them from regular text. A common example is [Press any key to continue].
void VerticalSpace(int count = 1)
Called when vertical space should be added to the output (basically a series of line breaks).
Task WaitForInput(bool hint)
Called when the system is waiting for user input. If hint is true, a hint should be displayed to the user, such as "[Press any key]". Can be asynchronous.
Task OnGameOver(string text)
Called when the game is over. This function should handle any necessary cleanup and display the final game state to the user. It should then either restart the game (using TextEngine.Start()) or exit the application. Can be asynchronous.
void LogWarning(string message)
Called in debug mode to display a warning message.
void LogError(string message)
Called in debug mode to display an error message.
Task Exit()
Called when the application (or the text engine part of it) should be terminated. Can be asynchronous.

Asynchronous Methods

Some methods in the ZodiacsTextEngine are asynchronous and return a Task that can be awaited. Asynchronous implementations can be used to wait for user input, a specific event, or a certain duration. If an implementation does not require asynchronous behavior, it should return a completed task using Task.CompletedTask. When using a normal console window, the use of async/await when requesting input is not strictly necessary, however, in GUI applications or game engines, asynchronous methods are often required to avoid blocking the main thread.

//Example of an asynchronous method implementation public async Task<ReadInput>() { //Wait until the user provides input //PlayerInput.Read() here has the return type Task<string> string input = await PlayerInput.Read(); return input; } //Example of a synchronous method implementation public Task<string> ReadInput() { //Always return "house" immediately return Task.FromResult("house"); }

Using a custom ContentLoader

The standard content loader is capable of loading story files from either a directory or a zip file from a given path. In the event that you need to load content from a different source (e.g. from an URL, game asset, etc.), you can create a custom content loader that supplies story files to the engine in a different way.

To register the custom content loader, it needs to be passed during engine initialization as mentioned above.

Example

using ZodiacsTextEngine; public class MyContentLoader : ContentLoader { private string rootDirectory; public MyContentLoader(string rootDirectory) { //Example constructor this.rootDirectory = rootDirectory; } protected override IEnumerable<Room> LoadRooms() { // Implement your own room file loading logic here // Each yield should return a new room yield return Room.Parse(story, "room1", Load(rootDirectory + "/room1")); yield return Room.Parse(story, "room2", Load(rootDirectory + "/room2")); yield return Room.Parse(story, "room3", Load(rootDirectory + "/room3")); SetStartRoom("room1"); } protected override IEnumerable<(string, FunctionDelegate)> LoadFunctions() { // Implement your own function loading logic or hardcode them here yield return ("MyFunction", async args => { // Your function logic here return "Function Result"; }); yield return ("AnotherFunction", async args => { // Another function logic here return "Another Result"; }); } }