Module: Gamefic::Active

Includes:
Messaging, Logging
Included in:
Actor
Defined in:
lib/gamefic/active.rb,
lib/gamefic/active/cue.rb,
lib/gamefic/active/messaging.rb,
lib/gamefic/active/narratives.rb

Overview

The Active module gives entities the ability to perform actions and participate in scenes. The Actor class, for example, is an Entity subclass that includes this module.

Defined Under Namespace

Modules: Messaging Classes: Cue, Narratives

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Messaging

#buffer, #flush, #messages, #messenger, #stream, #tell

Methods included from Logging

logger

Instance Attribute Details

#last_cue ⇒ Cue? (readonly)

The most recently started cue.

Returns:



20
21
22
 
# File 'lib/gamefic/active.rb', line 20

def last_cue
  @last_cue
end

#next_cue ⇒ Cue? (readonly)

The cue that will be started on the next turn.

Returns:



25
26
27
 
# File 'lib/gamefic/active.rb', line 25

def next_cue
  @next_cue
end

Instance Method Details

#accessible ⇒ Object 



159
160
161
 
# File 'lib/gamefic/active.rb', line 159

def accessible
  []
end

#acting? ⇒ Boolean

True if the actor performed a command this turn. False if the actor has not performed a command yet or has only performed meta commands.

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/gamefic/active.rb', line 191

def acting?
  @acting ||= false
end

#can?(verb) ⇒ Boolean

True if the actor can perform the verb (i.e., an active narrative understands it).

Parameters:

Returns:

  • (Boolean) 


173
174
175
 
# File 'lib/gamefic/active.rb', line 173

def can?(verb)
  narratives.understand?(verb)
end

#concluding? ⇒ Boolean

True if the actor is ready to leave the game.

Returns:

  • (Boolean) 


155
156
157
 
# File 'lib/gamefic/active.rb', line 155

def concluding?
  narratives.empty? || last_cue&.type == 'Conclusion'
end

#cue(scene, **context) ⇒ Cue Also known as: prepare

Cue a scene to start in the next turn.

Parameters:

  • scene (Class<Scene::Base>, Symbol)
  • context (Hash) —

    Extra data to pass to the scene’s props

Returns:

Raises:

  • (ArgumentError) —

    if the scene is not valid



137
138
139
140
141
142
143
 
# File 'lib/gamefic/active.rb', line 137

def cue scene, **context
  return @next_cue if @next_cue&.key == scene && @next_cue&.context == context

  logger.debug "Overwriting existing cue `#{@next_cue.key}` with `#{scene}`" if @next_cue

  @next_cue = Cue.new(self, scene, current, **context)
end

#execute(verb, *params) ⇒ Command?

Perform an action. This is functionally identical to the ‘perform` method, except the action must be declared as a verb with a list of arguments. Use `perform` if you need to parse a string as a command.

The command will be executed immediately, regardless of the entity’s state.

Examples:

character.execute :take, @key

Parameters:

  • verb (Symbol)
  • params (Array)

Returns:



94
95
96
97
98
99
100
 
# File 'lib/gamefic/active.rb', line 94

def execute(verb, *params)
  dispatchers.push Dispatcher.new(Order.new(self, verb, params))
  dispatchers.last.execute.tap do |command|
    dispatchers.pop
    @acting = true if command&.active?
  end
end

#last_input ⇒ String?

The input from the last finished cue.

Returns:



198
199
200
 
# File 'lib/gamefic/active.rb', line 198

def last_input
  output.last_input
end

#narratives ⇒ Narratives

The narratives in which the entity is participating.

Returns:



30
31
32
 
# File 'lib/gamefic/active.rb', line 30

def narratives
  @narratives ||= Narratives.new
end

#output ⇒ Props::Output

Data that will be sent to the user. The output is typically sent after a scene has started and before the user is prompted for input.

The output object attached to the actor is always frozen. Authors should use on_player_output blocks to modify output to be sent to the user.

Returns:



48
49
50
 
# File 'lib/gamefic/active.rb', line 48

def output
  last_cue&.output || Props::Output::EMPTY
end

#participating? ⇒ Boolean

True if the actor is participating in any narratives.

Returns:

  • (Boolean) 


165
166
167
 
# File 'lib/gamefic/active.rb', line 165

def participating?
  !narratives.empty?
end

#perform(input) ⇒ Command?

Perform a command.

The command’s action will be executed immediately, regardless of the entity’s state.

Examples:

Send a command as a string

character.perform "take the key"

Parameters:

Returns:



62
63
64
65
66
67
68
 
# File 'lib/gamefic/active.rb', line 62

def perform(input)
  dispatchers.push Dispatcher.new(Request.new(self, input))
  dispatchers.last.execute.tap do |command|
    dispatchers.pop
    @acting = true if command&.active?
  end
end

#proceed ⇒ Action?

Proceed to the next Action in the current stack. This method is typically used in Action blocks to cascade through multiple implementations of the same verb.

Examples:

Proceed through two implementations of a verb

introduction do |actor|
  actor[:has_eaten] = false # Initial value
end

respond :eat do |actor|
  actor.tell "You eat something."
  actor[:has_eaten] = true
end

respond :eat do |actor|
  # This version will be executed first because it was implemented last
  if actor[:has_eaten]
    actor.tell "You already ate."
  else
    actor.proceed # Execute the previous implementation
  end
end

Returns:



126
127
128
 
# File 'lib/gamefic/active.rb', line 126

def proceed
  dispatchers.last&.proceed
end

#queue ⇒ Array<String>

An array of commands waiting to be executed.

Returns:



37
38
39
 
# File 'lib/gamefic/active.rb', line 37

def queue
  @queue ||= []
end

#quietly(input) ⇒ String

Quietly perform a command. This method executes the command exactly as #perform does, except it buffers the resulting output instead of sending it to messages.

Parameters:

Returns:

  • (String) —

    The output that resulted from performing the command.



76
77
78
 
# File 'lib/gamefic/active.rb', line 76

def quietly(input)
  messenger.buffer { perform input }
end

#recue ⇒ Cue?

Restart the scene from the most recent cue.

Returns:



149
150
151
 
# File 'lib/gamefic/active.rb', line 149

def recue
  (@next_cue = @last_cue&.restart) || warn_nil('No scene to recue')
end

#rotate_cue ⇒ Cue?

Move next_cue into last_cue. This method is typically called by the narrator at the start of a turn. It returns the last cue.

Returns:



181
182
183
184
185
186
 
# File 'lib/gamefic/active.rb', line 181

def rotate_cue
  @acting = false
  @last_cue = @next_cue
  @next_cue = nil
  @last_cue
end