Text Adventure Package

ekelrock · October 11, 2021, 7:23am

This package was designed to help you build a text adventure game but it is very versatile and can be used in a number of interesting ways. Basically, any time you want to display text and buttons as options, this package can most likely help.

Before using this package, I highly recommend checking out the demo/showcase I built to see what it can do and how you might be able to use it in your game. The showcase has examples for using it as a tutorial, for conversations, to open doors, to answer questions, to teleport the player, and other use cases.

Demo: Text Adventure Package Showcase

And now, on to the details:

📖 How it works

The package is based on old “choose your own adventure” games and books. Unlike modern games, this genre gives you some text to read and some options for how to proceed. Your options you chose led you down different paths with different outcomes.

Basically, this package allows you to string together a bunch of “Steps” and then set “Options” that link you between the steps.

Steps are made up of a locator, a camera, and a script. The camera changes the view for the player and the locator (and the script on it) lets you define all the text, the options, and a bunch of other settings. Options are the buttons that appear at the bottom of each step. They represent the choices a player can make. Any step can have any number of options and they should each lead to another step. Below is an image of an example step view.

🛠️ Setup

Install the Text Adventure Package
Add the User Text Adventure template to your User template (Entity > Add Child > Script Folder > User Text Adventure)
Add at least one Text Adventure Step template to your world
Most likely add a bunch more steps and string them all together

⚙️ Config options

There are 2 configurable parts of this package: the userTextAdventureScript (on the User) and the textAdventureStepScript (on the Text Adventure Step).

On the User template, the userTextAdventureScript has 2 options:

Start on Init - If true, this script will automatically show the step when a player joins the game.
First Step - Only applicable Start on Init is true. This is the first step to show the player.
Initial Delay - Only applicable Start on Init is true. This is a delay before switching from the Player Camera to the camera set in the first step.

On each Text Adventure Step, there are properties that define sequence, camera, text, options, and player behavior. This is where you define the vast majority of the interactions and these properties let you do a lot unique and powerful things.

Step Camera - The camera to show the Player for this step.
Camera Change Duration - The amount of time to pan between the previous camera and this step’s camera.
Header Text - A title text for this step. Can be left blank.
Body Text - An array of strings to use for the main text of the step. Each item in the array will display as a separate paragraph.
Body Show If - An array of strings that correspond to the Body Text array. The corresponding Body Text will only be shown if the string in this array is found in the user data table. See Option Property To Save for more information.
Body Hide If - An array of strings that correspond to the Body Text array. The corresponding Body Text will be hidden if the string in this array is found in the user data table. See Option Property To Save for more information.
Options Text - An array of strings to use for the buttons that will show at the bottom of the screen.
Options Destinations - An array of entities. These should be set to other Text Adventure Steps in your world and each of the Options Text items should correspond to an Option Destination. Any unlinked Options Texts will end the sequence when pressed.
Option Show If - An array of strings that correspond to the Option Text array. The corresponding Option Text will only be shown if the string in this array is found in the user data table. See Option Property To Save for more information.
Option Hide If - An array of strings that correspond to the Option Text array. The corresponding Option Text will be hidden if the string in this array is found in the user data table. See Option Property To Save for more information.
Option Property To Save - An array of strings that correspond to the Option Text array. If the corresponding Option Text is selected, this string will be added to the user data table and will remain until cleared with the Clear User Data property or the Option Property To Remove property.
Option Property To Remove - An array of strings that correspond to the Option Text array. If the corresponding Option Text is selected, this string will be removed from the user data table (if it exists).
Player is Visible - Sets the player visibility for this step.
Move Player to Locator - If true, the player will be moved to this step’s main locator after the Camera Change Duration.
Auto Advance - If true, this step will auto advance to the defined next step after the set delay time.
Auto Advance Delay - The amount of time (in seconds) to show this step before proceeding to the next step.
Next Step - The next step to be shown in this sequence.
Show Widget - If false, the widget will be hidden for the duration of this step. This can be useful to show/highlight an area or object.
On This Step - Events to trigger on this step. This can be helpful for triggering animations while a player is looking at a certain step, changing visibility of entities, triggering motion, adjusting lights, etc…
Event If - An array of strings. If any of the strings in this array if found in the userData table then the events for this step will fire. If this array is empty, events on this step will always fire.
Events After Step - If true, events on this step will fire once the player finishes the step (ie: after pressing a button). Otherwise the events fire at the beginning of the step, after the Camera Change Duration.
Events On Server - If true, events will fire on the server.
Events On Client - If true, events will fire on the client.
Clear User Data - If true, the entire user data table will be cleared at the start of this step. This could be useful if your game is meant to be played multiple times and you want to clear all saved data at the end of the game.

📋 Helper scripts

Other:
This package also comes with two helper scripts: startTextAdventureScript and optionDestinationModifierScript.

The startTextAdventureScript is useful if you don’t want to start the sequence automatically when a player joins the game. Instead this script allows you to start the sequence manually, which allows you to have multiple sequences in your game. A practical example might be starting a sequence when a player enters a room (with a trigger) and a different sequence when they interact with a phone mesh. The startTextAdventureScript contains the following properties:

First Step - The starting step of the sequence you want to display.
Start On Interact - If true, the sequence will start when the entity containing this script is interacted with.
Start On Collision - If true, the sequence will start when the player collides with the entity containing this script.
Start On Trigger Enter - If true, the sequence will start when the player enters the trigger containing this script.
Only Start If - An array of strings. If this array contains any items, the sequence will only start if at least one of the strings is found in the userData table on the User. See “Option Property To Save” in the Config Options section for more info.

The optionDestinationModifierScript allows you to define multiple “next steps” for a single option and, if the option is selected, a random next step from the array will be shown. This could be useful if you want to add a random element to your sequence, like them finding a secret item 10% of the time. (Note: You can add multiple optionDestinationModifierScripts to the same text adventure step to randomize multiple options.) To use this functionality, add this script to a Text Adventure Step and configure it per the options below. The optionDestinationModifierScript contains the following properties:

Modify Option Number - The number (ie: array index) of the optionText to overwrite. For example, if this was set to 2 it would overwrite the second optionDestination and replace it with one of the destinations on this script.
Option Destinations - An array of entities that define all of the possible next steps in the sequence, should the player select the option defined in the “Modify Option Number”.
Option Destination Odds - The probability that the corresponding “Option Destination” will be selected. There must be one item in this array for each Option Destination and the numbers must always be >= 1. If you want all of the options to have the same odds, set them all to 1. Otherwise the odds will be based on the sum of the numbers. For example, if you have 3 Option Destinations and their corresponding Destination Odds are set to 1, 2, 1 then the odds would be 25%, 50%, 25%. If the Destination Odds were were set to 1, 2, 3 then the odds would be ~ 16%, 33%, 50%.

Here’s a short gif of how this package might be used to create a text adventure game:

As always, find me on the discord if you have questions or suggestions

09/18/21 Update - User data is now saved persistently. Use “Option Property To Save”, “Option Property To Remove”, and “Clear User Data” to manipulate the userData table.
09/19/21 Update - Added the helper script “optionDestinationModifierScript” and added a property (Only Start If) to the “startTextAdventureScript”.