Scenes

Gamefic plots use scenes to handle player interactions. Player characters participate in one scene per game turn.

How Scenes Work

Each scene has a start and a finish. The start is executed at the beginning of the turn. The finish is executed after the game engine receives player input.

The scene’s finish is typically responsible for processing the input. In a traditional text adventure, for example, the default scene’s finish will treat the input as a command to be performed by the player’s character.

Authors can select a scene with the Actor#cue method:

respond :finish do |actor|
  actor.tell "You're ending the game."
  actor.cue default_conclusion
end

The cued scene will start at the beginning of the next turn. Note that only one scene can be cued at a time. When a character cues a new scene, any previously cued scene is discarded.

Scene Types

There are seven basic scene types provided by the Gamefic core.

Activity

The default scene type for most plots. Activity parses player input into an action performed by the player’s character. In a text adventure, whenever players execute a command like GO NORTH or GET LAMP, they’re in an Activity scene.

The plot’s default_scene is Activity unless an author changes it.

Conclusion

A scene that ends the plot (or the player’s participation in it).

The plot provides a default_conclusion that can be used to end the game.

MultipleChoice

A scene that requires the player to select from one of several options. If the player does not select a valid option, the scene gets replayed.

YesOrNo

A MultipleChoice scene which can only proceed after the player selects Yes or No.

ActiveChoice

A scene that can optionally process a selection from a list of options. Unlike MultipleChoice, selecting an option is not required. The author can determine how the scene should treat input that does not match an option. The default behavior is to execute unmatched input as a command.

Pause

A scene that waits for player input before proceeding to the next turn. In a text adventure, for example, a Pause will ask the player to press enter to continue. This can be useful when the author wants to bring attention to a block of text or split a long passage into smaller parts.

Scene Methods

Plots (and other scriptable modules) provide several helper methods to simplify creation of various scene types. Scene methods typically accept procs that let you define on_start and on_finish callbacks for the scene to execute.

multiple_choice()

multiple_choice :pick_a_number do
  on_start do |actor, props|
    actor.tell 'Pick a number.'
    props.options.push 'one', 'two', 'three'
  end

  on_finish do |actor, props|
    actor.tell "You picked #{props.selection}."
    actor.tell "1-based option number: #{props.number}"
    actor.tell "0-based ption index: #{props.index}"
  end
end

introduction do |actor|
  actor.cue :pick_a_number
end

yes_or_no()

yes_or_no :pick_an_answer do
  on_start do |actor, props|
    actor.tell 'Yes or no?'
  end

  on_finish do |actor, props|
    actor.tell "You picked #{props.selection}."
    # YesOrNo props also provide `props.yes?` and `props.no?` helpers
  end
end

introduction do |actor|
  actor.cue :pick_a_number
end

pause()

The following example pauses the game in response to the READ command.

introduction do |actor|
  actor.tell "You're in a library."
end

respond :read do |actor|
  actor.cue :reading
end

pause :reading do |actor|
  actor.tell "You spend some time with a good book."
  actor.cue :default_scene
end

Example gameplay:

$ rake ruby:run

You're in a library.

> read

You spend some time with a good book.

Press enter to continue...

conclusion(&proc)

Add a conclusion scene. Running a conclusion ends the game.

class Mygame::Plot < Gamefic::Plot
  introduction do |actor|
    actor.tell "A mystery's afoot! Enter SOLVE to solve it."
  end

  respond :solve do |actor|
    actor.cue :solved
  end

  conclusion :solved do |actor|
    actor.tell 'You solved the mystery!'
  end
end

Custom Scenes

A custom scene, at its core, is simply a subclass of one of the various built-in Gamefic::Scene classes (Activity, MultipleChoice, etc.). The script methods for scenes (multiple_choice(), etc.) work by creating anonymous subclasses. Authors can also create their own scenes by defining the subclasses themselves.

module Mygame
  class MustSayNo < Gamefic::Scene::Base
    on_start do |actor, _props|
      actor.tell "This scene will keep repeating until you enter `no`."
    end

    on_finish do |actor, props|
      if props.input == 'no'
        actor.cue default_scene
      else
        actor.cue MustSayNo
      end
    end
  end

  class Plot < Gamefic::Plot
    introduction do |actor|
      actor.cue MustSayNo
    end
  end
end

Next: Scriptable modules