Gamefic

Adventure Games and Interactive Fiction

Scripting

Gamefic narratives have class methods that allow authors to define commands, build scenes, and implement game rules. Here’s a quick rundown of the methods available.

respond(verb, *arguments, &proc)

Create a command response. The proc gets executed when a command matches the response’s verb and arguments.

Simple example:

respond :think do |actor|
  actor.tell 'You ponder your predicament.'
end

Example with an argument:

respond :kick, Thing do |actor, thing|
  actor.tell "You kick #{the thing}."
end

Example of a custom response that targets a specific entity:

construct :ball, Item, name: 'soccer ball'

respond :kick, Thing do |actor, thing|
  actor.tell "You kick #{the thing}."
end

respond :kick, ball do |actor, _ball|
  actor.tell "You're playing soccer!"
end

meta(verb, *arguments, &proc)

Create a meta command response. A meta response is simply a response that’s flagged as meta (Response#meta?) to indicate that it’s an out-of-game action, such as displaying help documentation or a scoreboard.

before_command(*verbs, &proc)

Create a proc to be evaluated before a character executes an action. When a verb is specified, the proc will only be evaluated if the action’s verb matches it.

before_command :look do |actor, command|
  command.cancel
  actor.tell "You would have looked at #{command.arguments.first} now, but the command got cancelled."
end

after_command(*verbs, &proc)

Create a proc to be evaluated after a character executes an action. When a verb is specified, the proc will only be evaluated if the action’s verb matches it.

The after_command blocks do not get executed if the command was cancelled in a before_command block.

after_command :look do |actor, command|
  actor.tell "You just finished looking at something."
end

interpret(command, translation)

Define a syntax to be translated into another command. Parameters are prefixed with a colon(:).

interpret 'ponder', 'think' # When the user enters "ponder," it gets converted to the "think" command

interpret 'scrutinize :thing', 'look :thing' # "scrutizine object" gets converted to "look object"
end

verbs

Get a list of all the verbs defined in responses.

synonyms

Get a list of all verbs and synonyms.

This differs from verbs in that it will include verbs that get interpreted as other verbs. For example, gamefic-standard defines a take action and interprets get and carry as synonyms of take. The verbs array will include take, and the synonyms array will include take, get, and carry.

syntaxes

Get a list of all syntaxes.

introduction(&proc)

Create an introductory scene. This scene will run when a player enters the game.

entrance = construct :entrance, Room, name: 'entrance'

introduction do |actor|
  actor.parent = entrance
  actor.tell "You start the game at #{the entrance}."
end

on_ready(&proc)

Define a block of code to be executed every time a turn starts (i.e., before player input gets received).

seed { @turn_number = 0 }

on_ready do
  @turn_number += 1
end

on_player_ready(&proc)

Define a block of code to be executed for each player when a turn starts.

on_player_ready do |player|
  player.tell "The time is now #{Time.now}."
end

on_update(&proc)

Define a block of code to be executed every time a turn ends (i.e., after player input has been processed.)

on_update do
  # ...
end

on_player_update(&proc)

Define a block of code to be executed for each player when a turn ends.

on_player_update do |player|
  player.tell "You just finished a game turn and a new one is about to start."
end

on_player_conclude(&proc)

Define a block of code to be executed when a player reaches a conclusion.

on_player_conclude do |player|
  player.tell '***GAME OVER***'
end

on_player_output(&proc)

Define a block of code to be executed when player output is ready to render.

on_player_output do |actor, output|
  # Add a `:time` property to the output that gets sent to the game client.
  output[:time] = Time.now
end

Next: Running your game in a web browser

Quick Reference