Adventure Games and Interactive Fiction

Gamefic Updates: Option Sets, Action Rules, Debugging, and More

by Gamefic on July 13, 2014

Lots of major updates to Gamefic went online today. Everything discussed in this post has been pushed to the GitHub repo and the Ruby Gem.

Calling Actions with Tokens instead of Command Strings

It is now possible to pass tokens directly to Character#perform instead of a command string that gets parsed and tokenized. The first token is a symbol that corresponds to an action command (:go, :look, :take, etc.). The remainder of the tokens are objects to be validated against the corresponding actions' queries.


character.perform "take wallet from dresser" # A string that gets parsed and tokenized

character.perform :take, wallet, dresser # A set of tokens that bypass the parser

Benefits of using tokens:

  • Faster than parsing command strings.
  • Unambiguous identification of objects to be tokenized.

Intuitive Handling of Undefined "Not" Options

Calling will now return true when the :not_foo option is not defined in any of the entity's option sets. This resolves a confusing edge case where an entity can be :foo and :not_foo at the same time.

New System for Action Rules: Assert and Finish

The rules that can be applied to actions are now more robust and easier to use. There are two types of rules: assert and finish.

The assert rules are called before an action is performed. If any assert rule returns false, the action is not performed.

The finish rules are called after an action is completed.

Here's a simple example of an assert that stops characters from being able to drop items:

assert_action :do_not_allow_drop do |actor, action|
  if action == :drop or action == :drop_in or action == :drop_on
    actor.tell "You're not allowed to drop things."

Meta Actions

A meta is an action that is not intended to be performed within the context of the game world. Examples of meta actions are debugging commands, help and hint commands, save/restore/undo, and credits. Rules are not executed for meta actions, so they can always be performed even in scenarios where an assert would otherwise block an action.

Improved Character State Management

There's a new architecture for character states. The core provides four states: Active, Paused, Prompted, and Concluded.

  • ACTIVE - Prompt the player to enter a command. This is the default character state.
  • PAUSED - Pause the game, e.g., ask the player to press enter to continue.
  • PROMPTED - Ask the player for input that will be handled as a special case instead of a command.
  • CONCLUDED - This is equivalent to the old GameOverState. It is generally not necessary to set this state explicitly. The player's character will automatically enter this state after a conclusion.

New Features in Standard Import

  • Lockable containers. Container can be made :lockable and another entity can be defined as its key.
  • Intuitive traversal. The :go, :enter, and :leave actions are smarter about selecting appropriate destinations. For example, entering "sit down" will automatically target an enterable supporter, and "exit" will know how to leave the room if there is exactly one portal.

Additional Imports

  • Clothing. Items that can be worn.
  • Edible. Items that can be eaten.
  • Room Modes. BRIEF, SUPERBRIEF, and VERBOSE modes for determining whether to display room descriptions after using a portal.

Debugging Commands

Games running in test mode automatically import the "debug" library, which provides additional commands to assist authors.

  • analyze [entity]: Get information about an entity, such as its class and its current option settings.
  • options [class]: Get a list of option sets and their default settings for an entity class.
  • debug [on/off]: Output technical information about rules and actions, including the file name and line number where the rule or action was defined.

New Examples

The games in the repo's examples directory demonstrate a wider range of features.

  • Cloak of Darkness. The popular IF example game, updated to use the current features.
  • Professor. A very simple example of interaction with characters. It demonstrates how to customize a character's reaction to specific topics of conversation. It also provides an example of using the PROMPTED state to get additional input from the user, i.e., asking for a topic when none was specified in a :talk action.
  • Restaurant. A demonstration of the clothing and edible libraries. Eat dinner, put on your jacket, and go home.
  • Warehouse. A demonstration of supporters and containers, including enterable supporters (e.g., a chair) and a lockable container.

Please feel free to contact us or post an issue on GitHub if you have any questions or problems.