Subplots

Subplots are discrete narratives that happen inside a larger plot. They have most of the same features of a plot, with the additional features of encapsulation and disposability. The subplot maintains its own entities, actions, and scenes that are accessible to the plot but contained in a separate namespace. When the subplot concludes, it automatically cleans up its own data. Subplots can be started and concluded during runtime at will.

A Simple Example

In this example, the player enters the MagicWand subplot with the CONJURE command. The subplot concludes when the player waves the wand, and the wand is automatically destroyed.

require 'gamefic-standard'

class MagicWand < Gamefic::Subplot
  script do
    @wand = make Item, name: 'magic wand'
    
    introduction do |actor|
      actor.tell "You conjure a magic wand. WAVE it to make something happen."
      @wand.parent = actor
    end

    respond :wave, Use.available(@wand) do |actor, wand|
      actor.tell "The wand disappears in a puff of smoke."
      conclude
    end
  end
end

Gamefic.script do
  introduction do |actor|
    actor.tell "Use the CONJURE command to conjure a magic wand."
  end

  respond :conjure do |actor|
    branch MagicWand, introduce: actor
  end
end

Extending Gamefic::Subplot

Define subplots by extending Gamefic::Subplot. The subplot’s script method takes a block that will be executed when the subplot is instantiated, same as how Gamefic.script defines blocks for the main plot. Much like a regular plot, the subplot can have its own introduction, entities, actions, and scenes.

Accessing the Main Plot

The subplot has a plot method that points to its host. You can use it to get information about the plot’s entities, actions, etc. In this example, we query the plot’s entities to move the player to a random room:

class Hyperspace < Gamefic::Subplot
  script do
    introduction do |actor|
      room = plot.entities.that_are(Room).sample
      actor.parent = room
      actor.tell "You magically transport to #{the room}."
      conclude
    end
  end
end

If you want to make a permanent entity, you can use the plot’s make method instead of the subplot’s. Entities created with plot.make will continue to exist after the subplot concludes.

Starting a Subplot

The branch method starts a subplot. You can indicate an actor (usually the player’s character) to add to the subplot with the introduce parameter:

respond :jump do |actor|
  branch Hyperspace, introduce: actor
end

Ending a Subplot

Use the conclude method from inside the subplot to end it. This example will conclude the subplot with the command ABRACADABRA.

class Abracadabra < Gamefic::Subplot
  on_start do
    introduction do |actor|
      actor.tell "Say the magic word."
    end

    respond :abracadabra do |actor|
      actor.tell "Hocus pocus!"
      conclude
    end
  end
end

Scenes in Subplots

In addition to its own entities and actions, subplots can have their own scenes. Actors can prepare or cue them like any other scene.

class AskForConclusion < Gamefic::Subplot
  on_start do
    introduction do |actor|
      actor.tell "Enter FINISH to end the subplot."
    end

    respond :finish do |actor|
      actor.tell "Are you sure?"
      actor.cue @yes_or_no
    end

    @yes_or_no = yes_or_no do |actor, scene|
      if scene.yes?
        actor.tell "Okay, it's over."
        conclude
      else
        actor.tell "It's still running."
        actor.cue default_scene
      end
    end
  end
end

Rooms in Subplots

A subplot can make its own rooms, just like it can make any other entity. Keep in mind, however, that the subplot will destroy its rooms upon conclusion. Any plot entities, including the player’s character, will be ejected from the subplot’s rooms and left without a parent unless you explicitly set a new one.

Cueing a Scene after a Subplot Ends

The branch method can take a next_cue parameter that specifies which scene to cue after the subplot concludes. If next_cue is not specified, the conclusion cues the plot’s default_scene (typically the Activity scene that parses player commands).

Checking Active Subplots

The host plot has several methods for providing information about its running subplots.

• subplots: an array of all running subplots
• subplots_featuring(actor): an array of running subplots featuring a particular actor (i.e., the actor’s been introduced into the subplot)
• in_subplot?(actor): true if the actor is featured in any running subplot

Uses for Subplots

• Organizing scenes into logical groups
• Adding mini-games
• Procedurally generating quests
• Temporarily overriding actions
• Adding “private” areas to multiplayer games
• Encapsulating data to avoid naming conflicts

Next: Extending Gamefic with libraries