15. Exploring the StoryScript API

The StoryScript API is well documented, which should help you find all options available using your IDEs tools. As an example, let's use VS Code and find everything we can work with on enemies.

Open the enemy.ts file in your game's interfaces folder. It looks something like this:

export function Enemy(entity: IEnemy): IEnemy {
    return StoryScriptEnemy(entity);
}

export interface IEnemy extends IFeature, StoryScriptIEnemy {
    items?: IItem[];
    attack?: string;
}

Here, you can see the properties you've added for your own game. Now place your cursor on StoryScriptIEnemy and press F12 (Go to definition). This opens the StoryScript definition of an enemy, with all the properties and methods available. You can also see that an enemy is also a feature:

export interface IEnemy extends IFeature {
	...
}

So from here you can go deeper and see what properties are available on features.

Another very important part of StoryScript is your rules.ts file. In here, you can a.o. set up your character creation process and specify quite a few hooks to customize what to do when certain events happen during the game. For example, you can run some additional code when an enemy is defeated, when the game is started or when a location is entered. Note that the rules file contains a number of sections to help organize the hooks in a meaningful way:

export interface IRules {
    setup: ISetupRules,

    general?: IGeneralRules,

    character: ICharacterRules,

    exploration?: IExplorationRules,

    encounters?: IEncounterRules,

    combat?: ICombatRules
}

Also available are helper functions, that you can access via the game object. You can inspect the StoryScript IHelpers interface to see what functions are available. Amongst others, you can use these to roll dice or get random items in your code.

There are some additional things that are worth mentioning here:

• You can add images to entities that have the picture property (e.g enemies) by specifying the path of the image to use. The image should be present in your game's resources folder:
  

  picture: 'resources/bandit.jpg'

  A second option you have is to add it to the entities' HTML file instead, if it has one. Add it to the top of the file like this:

  <img class="picture" src="resources/bandit.jpg" />

• You’ve seen in the tutorials how to show messages to the player. There are three logs that you can write to, which show information in different places and which are also treated differently when e.g. refreshing the browser or loading the game:
  • LocationLog: using the game.logToLocation function, you can write messages to the location description shown to the player. The idea is that you use this log to show that things in the location have changed permanently. These messages will stay when the browser refreshes.
  • ActionLog: with game.logToActionLog, you write to the action log that should be used to show the player all the actions he’s done. That can be going from one location to the next, picking up an item, starting a fight, etc. This log is cleared at browser refreshes.
  • CombatLog: use game.logToCombatLog to show messages to the player during combat. The log will be cleared when combat is done.
  • ConversationLog: a bit of a special log, this one is not available on the game object. StoryScript uses this log to keep track of what’s been said during a conversation. This log is kept when the browser refreshes. You can get to it, though, by accessing the conversation object on a person in a location, if you really want to.

The inactive flag

A feature that deserves special attention as it can save you a lot of hassle from having to add stuff through code at runtime, which is great for making your game more dynamic, is the inactive flag. This flag is available for items, enemies, persons and destinations. Set this flag to true to NOT show the entity in the game until you set it to false from your code. In this way, you can populate your locations with persons, enemies and items when designing the game, but make some of them inactive and only
activate them when certain conditions have been met. I've used this to implement a day/night cycle in the Veils of Verdandi game, with some things that you can find at a location only at night and others only during the day.