Module: Gamefic::World::Commands

Includes:
Entities
Included in:
Gamefic::World, Players
Defined in:
lib/gamefic/world/commands.rb

Instance Method Summary collapse

Methods included from Entities

#cast, #destroy, #entities, #make, #pick, #players

Instance Method Details

#actions ⇒ Array<Action>

Get an Array of all Actions defined in the Plot.

Returns:



153
154
155
 
# File 'lib/gamefic/world/commands.rb', line 153

def actions
  playbook.actions
end

#disambiguate {|, | ... } ⇒ Object

Declare a dismabiguation response for actions. The disambiguator is executed when an action expects an argument to reference a specific entity but its query matched more than one. For example, “red” might refer to either a red key or a red book.

If a disambiguator is not defined, the playbook will use its default implementation.

Examples:

Tell the player the list of ambiguous entities.

disambiguate do |actor, entities|
  actor.tell "I don't know which you mean: #{entities.join_or}."
end

Yield Parameters:



113
114
115
 
# File 'lib/gamefic/world/commands.rb', line 113

def disambiguate &block
  playbook.disambiguate &block
end

#get_default_query ⇒ Object 



157
158
159
 
# File 'lib/gamefic/world/commands.rb', line 157

def get_default_query
  @default_query_class ||= Gamefic::Query::Family
end

#interpret(command, translation) ⇒ Syntax Also known as: xlate

Create an alternate Syntax for an Action. The command and its translation can be parameterized.

Examples:

Create a synonym for the Inventory Action.

interpret "catalogue", "inventory"
# The command "catalogue" will be translated to "inventory"

Create a parameterized synonym for the Look Action.

interpret "scrutinize :entity", "look :entity"
# The command "scrutinize chair" will be translated to "look chair"

Parameters:

  • command (String) —

    The format of the original command

  • translation (String) —

    The format of the translated command

Returns:

  • (Syntax) —

    the Syntax object



138
139
140
 
# File 'lib/gamefic/world/commands.rb', line 138

def interpret command, translation
  playbook.interpret command, translation
end

#meta(command, *queries) {|| ... } ⇒ Object

Create a Meta Action that responds to a command. Meta Actions are very similar to standard Actions, except the Plot understands them to be commands that operate above and/or outside of the actual game world. Examples of Meta Actions are commands that report the player’s current score, save and restore saved games, or list the game’s credits.

Examples:

A simple Meta Action

meta :credits do |actor|
  actor.tell "This game was written by John Smith."
end

Parameters:

  • command (Symbol) —

    An imperative verb for the command

  • queries (Array<Query::Base>) —

    Filters for the command’s tokens

Yield Parameters:



94
95
96
 
# File 'lib/gamefic/world/commands.rb', line 94

def meta(command, *queries, &proc)
  playbook.meta command, *queries, &proc
end

#override(command) {|| ... } ⇒ Class

Tokenize and parse a command to create a new Action subclass.

Parameters:

  • command (String) —

    The command

Yield Parameters:

Returns:

  • (Class) —

    the resulting Action subclass



73
74
75
76
77
 
# File 'lib/gamefic/world/commands.rb', line 73

def override(command, &proc)
  cmd = Syntax.tokenize(command, playbook.syntaxes).first
  raise "Unable to tokenize command '#{command}'" if cmd.nil?
  parse cmd.verb, *cmd.arguments, &proc
end

#parse(verb, *tokens, &proc) ⇒ Class

Parse a verb and a list of arguments into an action. This method serves as a shortcut to creating an action with one or more arguments that identify specific entities.

Examples:

@thing = make Entity, name: 'a thing'
parse "use", "the thing" do |actor, thing|
  actor.tell "You use it."
end

Parameters:

Returns:

  • (Class) —

    The resulting Action subclass

Raises:

  • (ArgumentError) —

    if tokens are unrecognized or ambiguous



56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/gamefic/world/commands.rb', line 56

def parse verb, *tokens, &proc
  query = Query::External.new(entities)
  params = []
  tokens.each do |arg|
    matches = query.resolve(nil, arg)
    raise ArgumentError, "Unable to resolve token '#{arg}'" if matches.objects.empty?
    raise ArgumentError, "Ambiguous results for '#{arg}'" if matches.objects.length > 1
    params.push Query::Family.new(matches.objects[0])
  end
  respond(verb.to_sym, *params, &proc)
end

#playbook ⇒ Gamefic::World::Playbook

Returns:



9
10
11
 
# File 'lib/gamefic/world/commands.rb', line 9

def playbook
  @playbook ||= Gamefic::World::Playbook.new
end

#respond(command, *queries) {|| ... } ⇒ Class Also known as: action

Create an Action that responds to a command. An Action uses the command argument to identify the imperative verb that triggers the action. It can also accept queries to tokenize the remainder of the input and filter for particular entities or properties. The block argument contains the code to be executed when the input matches all of the Action’s criteria (i.e., verb and queries).

Examples:

A simple Action.

respond :salute do |actor|
  actor.tell "Hello, sir!"
end
# The command "salute" will respond "Hello, sir!"

An Action that accepts a Character

respond :salute, Use.visible(Character) do |actor, character|
  actor.tell "#{The character} returns your salute."
end

Parameters:

  • command (Symbol) —

    An imperative verb for the command

  • queries (Array<Query::Base>) —

    Filters for the command’s tokens

Yield Parameters:

Returns:

  • (Class) —

    The resulting Action subclass



36
37
38
 
# File 'lib/gamefic/world/commands.rb', line 36

def respond(command, *queries, &proc)
  playbook.respond(command, *map_response_args(queries), &proc)
end

#set_default_query(cls) ⇒ Object 



161
162
163
 
# File 'lib/gamefic/world/commands.rb', line 161

def set_default_query cls
  @default_query_class = cls
end

#validate {|| ... } ⇒ Object

Validate an order before a character can execute its command.

Yield Parameters:

  • (Gamefic::Director::Order) 


120
121
122
 
# File 'lib/gamefic/world/commands.rb', line 120

def validate &block
  playbook.validate &block
end

#verbs ⇒ Array<String>

Get an Array of available verbs.

Returns:



146
147
148
 
# File 'lib/gamefic/world/commands.rb', line 146

def verbs
  playbook.verbs.map(&:to_s).reject { |v| v.start_with?('_') }
end