okaybenji / text-engine

   ████████ ███████ ██   ██ ████████               
      ██    ██       ██ ██     ██                  
      ██    █████     ███      ██     █████            
      ██    ██       ██ ██     ██                  
      ██    ███████ ██   ██    ██                  
                                                
███████ ███    ██  ██████  ██ ███    ██ ███████ 
██      ████   ██ ██       ██ ████   ██ ██      
█████   ██ ██  ██ ██   ███ ██ ██ ██  ██ █████   
██      ██  ██ ██ ██    ██ ██ ██  ██ ██ ██      
███████ ██   ████  ██████  ██ ██   ████ ███████

An HTML-based text adventure game engine. Small and easy to use with no dependencies. Highly customizable.

Very little programming is required, but several JavaScript hooks are provided if you are inclined to use them!

How do I use it?

To create your own adventure, you can use one of the files in the game-disks folder as a template. For example, take a look at the disk called newDiskTemplate.

Include your "game disk" (JSON data) in index.html and load it with loadDisk(myGameData). (Look at index.html in the repo for an example.)

The end product will be your very own text adventure game, similar to this one. It's a good idea to give that game a try to get introduced to the engine.

text-engine uses a disk metaphor for the data which represents your game, like the floppy disks of yore.

Including index.js from this repository in your index.html <script> adds a several functions to the global namespace. One of these is called loadDisk. loadDisk accepts a single argument, which is your disk -- a standard JavaScript object (JSON).

Disks

A disk is a JavaScript object which describes your game. At minimum, it must have these two top-level properties:

There are other properties you can choose to include if you like:

You can also attach any arbitrary data you wish. For instance, you could have a number called "health" that you use to keep track of your player's condition.

What's a room?

A room is a JavaScript object. You usually want a room to have the following properties:

Rooms can have these other optional properties as well:

What's an exit?

An exit is an object with the following properties:

An exit can optionally have a block as well:

What's an item?

An item is an object with a name:

Items can have these other optional properties as well:

What's a character?

A character is an object with the following properties:

Characters can have these other optional properties as well:

What's a topic?

A topic is something you can talk to a character about, and as you may have guessed, is a JavaScript object. A topic requires an option, and either a line or an onSelected function, or both:

Topics can have these other optional properties as well:

That's everything! If you've made a JSON object with a roomId and a list of rooms -- that is, a disk -- you've got a playable game!

How do I play it?

Just pass a reference to your disk to the loadDisk function. Take a look at index.html to see an example.

I've saved my disk to a const variable called demoDisk in game-disks/demo-disk.js. I've included that file and index.js in my HTML file, and added a script tag with a single line to call loadDisk(demoDisk). The game boots when index.html is loaded in a web browser.

You can use the included index.html file in your own project, or you can create your own.

Making your own HTML file

Sometimes you just want to start from scratch. If you wish to make your own HTML file, just be sure it contains the following two elements:

• A div with ID output. This is where the game text will appear.

<div id="output"></div>

• An input with ID input. This is where the player will enter commands.

<input id="input" autofocus>

Once your game is running, the player can use the following commands:

  LOOK:   'look at key'
  TAKE:   'take book'
  GO:     'go north'
  USE:    'use door'
  TALK:   'talk to mary'
  ITEMS:  list items in the room
  INV:    list inventory items
  SAVE:   save the current game
  LOAD:   load the last saved game
  HELP:   this help menu

Functions

Functions are reuseable bits of JavaScript code. text-engine provides several of these which you can use, for instance in callbacks like onUse, onLook, onEnter, etc.

Writing and using functions is optional, but they give you a great deal more flexibility with the sort of game you can make.

println

Print a line of text to the console. It takes up to two arguments:

pickOne

Get a random item from an array. It takes one argument:

getRoom

Get a reference to a room by its ID. It takes one argument:

enterRoom

Move the player to particular room. It takes one argument:

getExit

Get a reference to an exit by its direction name from a list of exits. It takes two argument:

getCharacter

Get a reference to a character. It takes up to two arguments:

getCharactersInRoom

Get an array containing references to each character in a particular room. It takes one argument:

getItemInRoom

Get a reference to an item in a particular room. It takes two arguments:

getItemInInventory

Get a reference to an item in the player's inventory. It takes one argument:

Commands

Every command a player can issue in the game has a corresponding function in text-engine.

For instance, there's a function called "go" that gets called when the player types GO.

You can add your own custom commands, as well. Take a look at the "unlock" command in game-disks/demo-disk.js for an example.

Overriding the default command set

If existing commands don't work how you want them to, you can override them by reassigning them to your own function code.

For instance, you may wish to implement your own versions of the "save" and "load" commands. Or you may not wish to include save or load at all.

Commands are stored on a global array called commands. Each element in the array is a JavaScript object with methods attached. The index of the element indicates how many arguments it accepts. So, for instance, all methods attached to commands[0] take zero arguments.

Methods are named according to what the player types to issue them. For instance, the player can type "go" with no arguments to see available exits in the room. This command is found at commands[0].go.

Here are a few examples of ways to override the default commands:

// Add a command which takes no arguments.
// In this example, the command is called "play", and the user would type "play" to use the command.
const play = () => println(`You're already playing a game!`);
commands[0] = Object.assign(commands[0], {play});

// Override a command's function.
// In this example, we're overriding the "save" command.
save = () => println(`Sorry, saving is not supported in this game.`);

// Remove an existing command.
// In this example, we're removing the "save" command.
delete commands[0].save;

// Completely replace existing commands.
// In this example, the only two commands available in the entire game will be "walk" and "talk".
commands = [{walk: () => println(‘you walk’), talk: () => println(‘you talk’)}];

If you do remove some or all of the default commands, you'll want to override the help function as well so that it doesn't list commands which are not supported by your game.

Other Functions

There are several other functions available in the engine! Feel free to take a peek at the source code. It's designed to be open and simple to use and to customize.

A word of caution regarding SAVE/LOAD

The default implementation of saving and loading games in text-engine is quite simple. It converts the current state of the entire game disk to a string and saves that to your browser's Local Storage.

This simplicity comes at a cost. Here there be dragons. There are several things you must keep in mind as you write your disk if you want the built-in save functionality to work correctly.

Before we get to that list, I'd like to remind you that these commands can be removed from your game, or you can write your own save/load functions. (See Overriding the default command set above.)

Without further ado, here are the requirements for supporting the built-in "save" and "load" commands:

• If you publish changes to your game disk, old saves are not likely to be compatible. This is because the save contains the entire disk, and loading the save overwrites the new disk with the old one.
• Certain keywords such as "key" and "window" must be avoided as object names (because these are reserved by JavaScript and will not survive the parse). The recommended way around this is to add adjectives to your names, such as "silver key" or "tall window".
• Circular JSON structures are not supported (a property cannot point to its object's ancestor).

If you are writing functions for your game, you'll need to keep these in mind as well:

• Functions attached to the disk must not rely on closures. Closures are lost when a JSON object is converted to a string representation.
• You cannot use the shorthand syntax for defining methods. That is,

{
  onUse() {
    // This version will not work.
  },
  onUse: () => {
    // This one is okay!
  },
}

Etc.

Useful Tools

• REXPaint - Makes creating ASCII art super easy.
• ASCII-Code.com - Convenient for copying and pasting ASCII characters.
• Text to ASCII Art Generator - Make ASCII logos from text.

Acknowledgments

• Engine inspired in part by TextAdventure.js.
• Unlimited Adventure demo inspired by Forgotten by Sophia Park, Arielle Grimes, and Emilie Sovis and also this screenshot, whatever it is.
• "Ultimate Apple II Font" from KreativeKorp.
• Some ASCII art adapted from ASCII Art Archive.
• Special thanks to Caleb Creed for helping me flesh out the features for text-engine 2.0 and for designing and writing the auto-complete functionality.

Updates

• 2.0.0: Added characters, conversations, auto-complete, items command, save & load commands, navigation shortcuts, global methods for utility or overriding, support for custom commands, onLook & onTalk callbacks, upgraded go command, support for blocks on exits, support for providing class name to println function, support for randomizing printed lines, bold/italic/underline text, various bug fixes & improvements.
• 1.3.0: Rooms can define onEnter methods.
• 1.2.0: New orange default theme.
• 1.1.1: Now supports use in other operating environments besides the DOM. See text-engine-node for example usage. (Planning to add documentation later.)