SES Switches and Variables

#═╦═════════════════════════════════════════════════════════════════════════════
# ║ § Switches and Variables (1.0) by Solistra           [License: CC BY-SA 3.0]
# ║                                                             <RMVX Ace>
#═╬═════════════════════════════════════════════════════════════════════════════
# ║ § Change Log
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ v1.0 (July 16th, 2013) - Initial release
# ║
#═╬═════════════════════════════════════════════════════════════════════════════
# ║ § Summary
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ This script allows you to access and use switches, variables, and event
# ║ self-switches in a more flexible manner than that used by RMVX Ace by
# ║ default. Most notably, you can access these elements by name rather than
# ║ by numerical index only -- which is particularly useful with event self-
# ║ switches. This script also allows you to specify default starting values
# ║ for switches, variables, and event self-switches.
# ║
#═╬═════════════════════════════════════════════════════════════════════════════
# ║ § Script Calls
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ Switches, variables, and event self-switches may be accessed normally when
# ║ using this script if desired. For instance, these are still acceptable:
# ║   $game_switches[5]
# ║   $game_self_switches[[22, 5, "C"]]
# ║
# ║ In addition to this, however, any of these elements may be accessed by the
# ║ names that the user has designated for them in the editor like so:
# ║   $game_switches["Switch name"]
# ║   $game_variables["Variable name"]
# ║   $game_self_switches["Map name", "Event name", "A"]
# ║
# ║ In the case of event self-switches, you may optionally use map and event
# ║ names or not. The script call $game_self_switches["Map name", 5, "A"] is
# ║ still perfectly valid to access the "A" switch of event ID 5 on "Map name".
# ║
# ║ This script also allows you to toggle switch and event self-switch values:
# ║   $game_switches.toggle!("Switch name or ID")
# ║   $game_self_switches.toggle!("Map name", "Event name", "A")
# ║
# ║ For scripters, you may now also add actions to be evaluated whenever an
# ║ assignment is performed on switches, variables, or event self-switches.
# ║ Adding an action to be evaluated is simple:
# ║   $game_switches.actions.push('puts "#{index} assigned to #{value}"')
# ║
# ║ Actions are strings which are evaluated within the context of the instance.
# ║ For more detailed information, consult the documentation of this script.
# ║
#═╬═════════════════════════════════════════════════════════════════════════════
# ║ § Caveats
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ Accessing elements by name presents a problem if there is more than one
# ║ switch, variable, map, or event with the same name. In this case, the first
# ║ name found is the one used to access its associated element.
# ║
# ║ Also, while the previous form of indexing event self-switches still works,
# ║ it has actually been changed. Before, you had to pass an array -- now, you
# ║ are encouraged not to. Example:
# ║   $game_self_switches[[1, 1, 'A']] = true # Previous form.
# ║   $game_self_switches[1, 1, 'A']   = true # New form.
# ║
#═╬═════════════════════════════════════════════════════════════════════════════
# ║ ▼ module SES
#═╩═════════════════════════════════════════════════════════════════════════════
module SES
  module Switches
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ α BEGIN CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
    # An array of switch indices which should be enabled by default whenever the
    # game is started. Switch indices may be given by name or literal index.
    # Example:
    #   INITIALIZE = [ 1, 5, 'Switch name', 99 ]
    INITIALIZE = []
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ Ω END CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
  end

  module Variables
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ α BEGIN CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
    # A hash of variables where indices are keys and initial values are the hash
    # values. Variable indices may be given by name or literal index.
    # Example:
    #    INITIALIZE = {
    #      'Variable name' => 25, # Don't forget the comma.
    #      1 => 10
    #    }
    INITIALIZE = {

    }
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ Ω END CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
  end

  module SelfSwitches
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ α BEGIN CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
    # An array of self switches where elements are arrays referencing the event
    # and the desired self switch. The map and event indices of the array may be
    # given by name or literal index. The order of elements in the array is
    # fixed, and must always be given as [ map, event, self_switch ].
    # Example:
    #    INITIALIZE = [
    #      [ 'Map Name', 'Event Name', 'A' ], # Don't forget the comma.
    #      [ 1, 5, 'D' ]
    #    ]
    INITIALIZE = [

    ]
    #═╦═════════════════════════════════════════════════════════════════════════
    # ║ Ω END CONFIGURATION
    #═╩═════════════════════════════════════════════════════════════════════════
  end
  #═╦═══════════════════════════════════════════════════════════════════════════
  # ║ ▼ module SES::DataWrapper
  #═╩═══════════════════════════════════════════════════════════════════════════
  # This module provides a simple wrapper around the data structure represented
  # by the @data instance variable. Note: this module is intended to be mixed in
  # to user-created classes rather than used on its own.
  module DataWrapper
    include Enumerable

    # Classes mixing in this module are expected to provide a data structure to
    # wrap around which is represented by the @data instance variable. Arrays
    # are recommended.
    attr_reader :data

    # Classes mixing in this module are expected to provide an @actions instance
    # variable corresponding to an array of actions to be carried out by the
    # class on assignment. Actions must be written as strings to be passed to
    # Kernel.instance_eval.
    attr_reader :actions

    # Provides a default action to be used by classes mixing in this module.
    # This action will cause the map to refresh if an instance of $game_map is
    # defined.
    def self.default_action
      '$game_map.need_refresh = true if $game_map'
    end

    # Returns inspection of the base data.
    def inspect
      @data.inspect
    end
    alias :to_s :inspect

    # Returns the value stored in the base data structure's given index.
    def [](index)
      @data[obtain(index)]
    end

    # Assigns the given value to the given index, then calls the on_assignment
    # method to carry out actions post-assignment.
    def []=(index, value)
      @data[obtain(index)] = value
      on_assignment(index, value)
    end

    # Returns the underlying base data structure as an array when an array
    # representation is requested.
    def to_ary
      @data.to_ary rescue @data.to_a
    end
    alias :to_a :to_ary

    # Facilitates Enumerable functionality for the wrapper. This method allows
    # the use of many others that should be familiar to Ruby scripters (such as
    # each_with_index, collect, reduce, and so on). Returns the underlying data
    # structure if no block is given.
    def each
      block_given? ? @data.each { |element| yield element } : @data
    end

    # Evaluates all actions for the wrapper after an assignment has been
    # performed. The @actions instance variable will be initialized to a default
    # array if it has not already been assigned.
    def on_assignment(index, value)
      (@actions ||= [ self.default_action ]).each do |action|
        instance_eval(action)
      end
    end

    # Method intended to facilitate finding an index for the base data class by
    # name. Any class mixing in this module is expected to redefine this method
    # for specific use cases.
    def obtain(index)
      index
    end
  end
  #═╦═══════════════════════════════════════════════════════════════════════════
  # ║ ▲ module SES::DataWrapper
  #═╩═══════════════════════════════════════════════════════════════════════════
end
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▲ module SES
#═╩═════════════════════════════════════════════════════════════════════════════
            ($imported ||= {})['SES - Switches and Variables'] = 1.0
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▼ class Game_Switches
#═╩═════════════════════════════════════════════════════════════════════════════
class Game_Switches
  include SES::DataWrapper

  def initialize
    # The base data array. The first element is not used by RPG Maker VX Ace.
    @data    = [ nil ]

    # An array of actions to be carried out in sequence when the on_assignment
    # method is called on the wrapper.
    @actions = [ SES::DataWrapper.default_action ]

    # Initialization of switches specified in the SES::Switches module. All
    # given switches are initialized to a true value.
    SES::Switches::INITIALIZE.each { |index| self[index] = true }
  end

  # Redefines inspection of the wrapper class to the wrapper's representation as
  # an array. For the unaltered data array, use $game_switches.data.inspect.
  def inspect
    to_ary.inspect
  end
  alias :to_s :inspect

  # Returns an array where all elements of the base data array have been given
  # explicit true, false, or nil values to reflect the intended use of the
  # class. Use $game_switches.data to obtain the unaltered array.
  def to_ary
    @data.map { |element| element ? true : false unless element.nil? }
  end
  alias :to_a :to_ary

  # Redefinition of the Game_Switches class' original [] method to allow the
  # ability to reference indices by name as well as their actual index. Also
  # explicitly returns only true or false values rather than the actual contents
  # of the base data array (to access actual contents, use the data method).
  def [](index)
    @data[obtain(index)] ? true : false
  end

  # Redefinition of the Game_Switches class' original []= method to allow the
  # ability to reference indices by name as well as their actual index. Values
  # passed to this method are automatically converted to true or false. Also
  # calls the on_assignment method to carry out actions post-assignment.
  def []=(index, value)
    index = obtain(index)
    @data[index] = value ? true : false
    on_assignment(index, value)
  end

  # Toggles the switch at the given index. Note: toggled values will always be
  # "true" or "false," not necessarily the return value of a unary ! operation
  # on the element contained by the index due to the class' []= method.
  def toggle!(index)
    index = obtain(index)
    self[index] = begin !@data[index] rescue !self[index] end
  end

  # Attempts to find the location of the given index by name. Returns the given
  # index if the name cannot be found.
  def obtain(index)
    $data_system.switches.index(index) || index
  end
end
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▲ class Game_Switches
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ ▼ class Game_Variables
#═╩═════════════════════════════════════════════════════════════════════════════
class Game_Variables
  include SES::DataWrapper

  def initialize
    # The base data array. The first element is not used by RPG Maker VX Ace.
    @data    = [ nil ]

    # An array of actions to be carried out in sequence when the on_assignment
    # method is called on the wrapper.
    @actions = [ SES::DataWrapper.default_action ]

    # Initialization of variables defined in the SES::Variables module.
    SES::Variables::INITIALIZE.each { |index, value| self[index] = value }
  end

  # Redefinition of the Game_Variables class' original [] method to allow the
  # ability to reference indices by name as well as their actual index. Also
  # returns a 0 value if the value at the index is false or nil.
  def [](index)
    @data[obtain(index)] || 0
  end

  # Redefinition of the Game_Variables class' original []= method to allow the
  # ability to reference indices by name as well as their actual index. Also
  # calls the on_assignment method to carry out actions post-assignment.
  def []=(index, value)
    index = obtain(index)
    @data[index] = value
    on_assignment(index, value)
  end

  # Attempts to find the location of the given index by name. Returns the given
  # index if the name cannot be found.
  def obtain(index)
    $data_system.variables.index(index) || index
  end
end
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▲ class Game_Variables
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ ▼ class Game_SelfSwitches
#═╩═════════════════════════════════════════════════════════════════════════════
class Game_SelfSwitches
  include SES::DataWrapper

  def initialize
    # The base data hash.
    @data    = {}

    # An array of actions to be carried out in sequence when the on_assignment
    # method is called on the wrapper.
    @actions = [ SES::DataWrapper.default_action ]

    # Initialization of switches specified in the SES::SelfSwitches module. All
    # given switches are initialized to a true value.
    SES::SelfSwitches::INITIALIZE.each { |index| self[index] = true }
  end

  # Redefines inspection of the wrapper class so that all values are represented
  # by true, false, or nil values to reflect the intended use of the class. To
  # get the unaltered hash, use $game_self_switches.data.inspect.
  def inspect
    to_hash.inspect
  end
  alias :to_s :inspect

  # Returns a hash where all values of the base hash have been given explicit
  # true, false, or nil values to reflect the intended use of the class. Use
  # $game_self_switches.data to obtain the unaltered hash.
  def to_hash
    @data.each_with_object({}) do |(key, value), hash|
      hash[key] = value ? true : false unless value.nil?
    end
  end

  # Redefinition of the Game_SelfSwitches class' original [] method to allow the
  # ability to reference indices by name as well as their actual index. Also
  # explicitly returns only true or false values rather than the actual contents
  # of the base data array (to access actual contents, use the data method).
  def [](map, event = nil, switch = nil)
    @data[obtain(parse_index(map, event, switch))] ? true : false
  end

  # Redefinition of the Game_SelfSwitches class' original []= method to allow
  # the ability to reference indices by name as well as their actual index.
  # Values passed to this method are automatically converted to true or false.
  # Also calls the on_assignment method to carry out actions post-assignment.
  def []=(map, event = nil, switch = nil, value)
    index = parse_index(map, event, switch)
    @data[obtain(index)] = value ? true : false
    on_assignment(index, value)
  end

  # Toggles the switch at the given index. Note: toggled values will always be
  # "true" or "false," not necessarily the return value of a unary ! operation
  # on the element contained by the index due to the class' []= method.
  def toggle!(map, event = nil, switch = nil)
    index = obtain(parse_index(map, event, switch))
    self[index] = begin !@data[index] rescue !self[index] end
  end

  # This method parses the information given to it into an index usable by this
  # class' obtain method. This method is what enables multiple index formats for
  # the wrapper. Note: this is a private method.
  def parse_index(map_id, event_id, switch_id)
    # If event_id is nil, we assume that map_id contains an array to parse.
    # Otherwise, we build it.
    index = (event_id ? [map_id, event_id] : map_id)
    index.push(switch_id) if switch_id
    index.unshift($game_map.map_id) if index.length == 2
    index
  end

  # Attempts to find the names for given map and event indices present in the
  # index if the elements representing the map and event resemble Strings. This
  # method tries to perform substitution for these elements and returns an array
  # with the actual values used by the underlying data hash.
  def obtain(index)
    if index[0].respond_to?(:to_str)
      $data_mapinfos.each { |id, m| index[0] = id if m.name == index[0].to_str }
    end
    if index[1].respond_to?(:to_str)
      # Get the RPG::Map instance to use for accessing RPG::Event instances.
      # Using $game_map does not provide events with a name method, which is
      # required for this method to work properly.
      if !$game_map || $game_map.map_id != index[0]
        load_data(sprintf('Data/Map%03d.rvdata2', index[0]))
      else
        $game_map.map
      end.events.each { |id, e| index[1] = id if e.name == index[1].to_s }
    end
    index
  end

  private :parse_index
end
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▲ class Game_SelfSwitches
#─╫─────────────────────────────────────────────────────────────────────────────
# ║ ▼ class Game_Map
#═╩═════════════════════════════════════════════════════════════════════════════
class Game_Map
  # Allows accessing the RPG::Map instance used by Game_Map directly.
  attr_reader :map
end
#═╦═════════════════════════════════════════════════════════════════════════════
# ║ ▲ class Game_Map
#═╩═════════════════════════════════════════════════════════════════════════════
# Removing the sort and sort_by methods for the default VX Ace switch, variable,
# and self switch data structures -- these structures are inherently in order.
[Game_Switches, Game_Variables, Game_SelfSwitches].each do |structure|
  [:sort, :sort_by].each { |method| structure.send(:undef_method, method) }
end
#═╦══════════════════════════════════════════════════════════════════════════╦═#
# ║                              ▼ END OF FILE ▼                             ║ #
#═╩══════════════════════════════════════════════════════════════════════════╩═#