sabrina 0.5.5

data/lib/sabrina/meta.rb

@@ -0,0 +1,33 @@
+module Sabrina
+  # Current software version.
+  #
+  # @return [String]
+  VERSION = '0.5.5'
+
+  # Date of the current version.
+  #
+  # @return [String]
+  DATE = '2014-10-12'
+
+  # A short description.
+  #
+  # @return [String]
+  ABOUT = 'Hack GBA ROMs of a popular monster collection RPG series.'
+
+  class << self
+    # Gets the PNG handler info.
+    def png
+      PNG
+    end
+
+    # @see VERSION
+    def version
+      "#{VERSION}/#{PNG}"
+    end
+
+    # @see ABOUT
+    def about
+      ABOUT
+    end
+  end
+end

data/lib/sabrina/monster.rb

@@ -0,0 +1,147 @@
+module Sabrina
+  # An abstract class for dealing with further abstractions of data related
+  # to a specific, numbered monster.
+  #
+  # See {Sabrina::Plugins} for extensions that might enhance this class
+  # with added functionality.
+  class Monster
+    include ChildrenManager
+
+    # @!attribute rom
+    #   The current working ROM file.
+    #   @return [Rom]
+    # @!method rom=(r)
+    #   The current working ROM file.
+    #   @param [Rom] r
+    #   @return [Rom]
+    # @!attribute index
+    #   The real index of the monster.
+    #   @return [Integer]
+    # @!method index=(i)
+    #   The real index of the monster.
+    #   @param [Integer] i
+    #   @return [Integer]
+    attr_children :rom, :index
+
+    # The filename for saving data to a file, sans the path and extension.
+    # Refer to {#work_dir=} for setting the path, and child +#save+
+    # methods should take care of adding the right extension.
+    #
+    # @return [String]
+    attr_reader :filename
+
+    # The directory for reading and saving file data.
+    # Defaults to the current ROM's file name affixed with +_files+.
+    #
+    # @return [String]
+    # @see #work_dir=
+    attr_reader :work_dir
+
+    # The effective dex number of the monster, depending on any blanks
+    # in the ROM file.
+    attr_reader :dex_number
+
+    class << self
+      # Calculates the real index by parsing the provided index either
+      # as a dex number (when integer) or as a string. A number string
+      # prefixed with an exclamation mark +"!"+ will be interpreted as
+      # the real index.
+      #
+      # @param [Integer, String] index either the dex number, or the
+      #   real index prepended with "!".
+      # @param [Rom] rom the rom file to pull the dex data from.
+      # @return [Integer] the real index of the monster in the ROM file,
+      #   after accounting for blank spaces between dex numbers 251 and 252.
+      def parse_index(index, rom)
+        in_index = index.to_s
+        if /[^0-9\!]/ =~ in_index
+          fail "\'#{in_index}\' does not look like a valid index."
+        end
+
+        out_index =
+          if in_index['!']
+            in_index.rpartition('!').last.to_i
+          else
+            i = in_index.to_i
+            i < rom.dex_blank_start ? i : i + rom.dex_blank_length
+          end
+
+        unless out_index < rom.dex_length
+          fail "Real index #{out_index} out of bounds;" \
+            " #{rom.id} has #{rom.dex_length} monsters."
+        end
+
+        out_index
+      end
+    end
+
+    # Generates a new instance of Monster.
+    #
+    # @param [Rom] rom the ROM to be associated with the monster.
+    # @param [Integer] index either the dex number of the monster,
+    #   or the real (ROM) index prefixed with "!". See {parse_index}
+    #   for details.
+    # @param [String] dir the working directory.
+    # @return [Monster]
+    def initialize(rom, index, dir = nil)
+      @plugins = {}
+
+      @rom = rom
+      @index = self.class.parse_index(index, @rom)
+      @dex_number = index
+
+      @filename = format('%03d', @index)
+      @work_dir = dir || @rom.filename.dup << '_files/'
+
+      load_plugins
+    end
+
+    # @return [Array]
+    # @see ChildrenManager
+    def children
+      @plugins.values
+    end
+
+    # Sets the path for saving data to a file.
+    #
+    # @param [String] path
+    # @return [String]
+    def work_dir=(path)
+      path << '/' unless path.end_with?('/')
+      @work_dir = path
+    end
+
+    alias_method :dir=, :work_dir=
+
+    # Sets the dex number of the monster, dependent on any blanks in the ROM.
+    #
+    # @return [Integer]
+    # @see parse_index
+    def dex_number=(n)
+      @dex_number = n
+      self.index = self.class.parse_index(n, @rom)
+    end
+
+    # Reads the monster name from the ROM.
+    #
+    # @return [String]
+    def name
+      @rom.monster_name(@index)
+    end
+
+    # Closes the ROM file.
+    #
+    # @return [0]
+    def close
+      @rom.close
+      0
+    end
+
+    # Prints a blurb consisting of the monster's dex number and name.
+    #
+    # @return [String]
+    def to_s
+      "#{@index}. #{name}"
+    end
+  end
+end

data/lib/sabrina/palette.rb

@@ -0,0 +1,216 @@
+module Sabrina
+  # A class dedicated to handling color palette data inside a ROM file.
+  # This must be used alongside sprites to display the correct colors
+  # in game or when exported to files.
+  #
+  # While a palette will function in this and some other programs even if
+  # smaller than 16 colors, it must have exactly 16 colors to work in-game.
+  # To ensure this, use the {#pad} method to fill the remaining slots with
+  # a default color. This will, however, make it impossible to add further
+  # colors.
+  #
+  # Parts adapted from
+  # {https://github.com/thekaratekid552/Secret-Tool Gen III Hacking Suite}
+  # by thekaratekid552.
+  #
+  # @see Sprite#set_palette
+  class Palette < Bytestream
+    class << self
+      # Generates an array of two palettes from two +0xRRGGBB+-format streams:
+      # One containing every color from +rgb1+, and another where each color is
+      # replaced with its spatial equivalent from +rgb2+. This assumes
+      # palette 1 does not contain duplicate entries, but palette 2 might.
+      #
+      # @param [String] rgb1 a string of +0xRRGGBB+ values.
+      # @param [String] rgb2 a string of +0xRRGGBB+ values.
+      # @param [Hash] h1 see {Bytestream#initialize}
+      # @param [Hash] h2 see {Bytestream#initialize}
+      # @return [Array] an array of the two resulting palettes.
+      def create_synced_palettes(rgb1, rgb2, h1 = {}, h2 = {})
+        unless rgb1.length % 3 == 0 && rgb2.length % 3 == 0
+          fail 'RGB stream length must divide by 3.'
+        end
+
+        a1, a2 = rgb1.scan(/.../), rgb2.scan(/.../)
+        pal1, pal2 = Palette.empty(h1), Palette.empty(h2)
+
+        a1.each_index do |i|
+          pix1 = a1[i].unpack('CCC')
+          next if pal1.index_of(pix1)
+
+          pix2 = a2[i].unpack('CCC')
+          pal1.add_color(pix1)
+          pal2.add_color(pix2, force: true)
+        end
+
+        [pal1.pad, pal2.pad]
+      end
+
+      # Same as {ByteInput#from_table_as_pointer}.
+      #
+      # @param [Hash] h see {Bytestream#initialize}
+      # @return [Palette]
+      # @see ByteInput#from_table_as_pointer
+      def from_table(rom, table, index, h = {})
+        from_table_as_pointer(rom, table, index, h)
+      end
+
+      # Generates a palette from a stream of bytes following the +0xRRGGBB+
+      # format, failing if the total number of colors in the palette exceeds 16.
+      #
+      # @param [String] rgb
+      # @param [Hash] h see {Bytestream#initialize}
+      # @return [Sprite]
+      def from_rgb(rgb, h = {})
+        fail 'RGB stream length must divide by 3.' unless rgb.length % 3 == 0
+        out_pal = empty(h)
+
+        until rgb.empty?
+          pixel = rgb.slice!(0, 3).unpack('CCC')
+          out_pal.add(pixel) unless out_pal.index_of(pixel)
+        end
+
+        out_pal
+      end
+
+      # Returns an object representing an empty palette.
+      #
+      # @param [Hash] h see {Bytestream#initialize}
+      # @return [Palette]
+      def empty(h = {})
+        h.merge!(representation: [])
+        new(h)
+      end
+
+      # Returns a palette object represented by the given array
+      # of [R,G,B] values. Caution is advised as there is no
+      # validation.
+      #
+      # @param [Array] a
+      # @return [Palette]
+      def from_array(a = [], h = {})
+        h.merge!(representation: a)
+        new(h)
+      end
+    end
+
+    # Same as {Bytestream#initialize}, but with +:lz77+
+    # and +:pointer_mode+ set to true by default.
+    #
+    # @see Bytestream#initialize
+    def initialize(h = {})
+      @lz77 = true
+      @pointer_mode = true
+
+      super
+    end
+
+    # Pads the palette until it has the specified number of colors.
+    # This is a mandatory step for the palette to actually work in-game.
+    #
+    # @param [Integer] l target size.
+    # @param [Array] c the color to pad with, following the [R, G, B] format.
+    # @return [self]
+    def pad(l = 16, c = [16, 16, 16])
+      add_color(c, force: true) until present.length >= l
+      clear_cache
+    end
+
+    # Adds a color to the array. The color must be a [R, G, B] array.
+    # Will fail on malformed color or 16 coors exceeded.
+    #
+    # This will clear the internal cache.
+    #
+    # @param [Array] color the color in [255, 255, 255] format.
+    # @param [Hash] h
+    #   @option h [Boolean] :force if +true+, add colors even if already
+    #     present in the palette.
+    # @return [self]
+    def add_color(color, h = {})
+      unless color.is_a?(Array) && color.length == 3
+        fail "Color must be [R, G, B]. (#{color})"
+      end
+
+      color.each do |i|
+        next if i.between?(0, 255)
+        fail "Color component out of bounds. (#{color})"
+      end
+
+      @representation ||= []
+
+      if @representation.index(color) && !h.fetch(:force, false)
+        return clear_cache
+      end
+      @representation << color
+
+      if present.length > 16
+        fail "Palette must be smaller than 16. (#{present.length}, #{color})"
+      end
+
+      clear_cache
+    end
+
+    alias_method :add, :add_color
+
+    # Returns the index of the [R, G, B] color in the palette,
+    # or +nil+ if absent.
+    #
+    # @param [Array] color the color in [255, 255, 255] format.
+    # @return [Integer]
+    def index_of(color)
+      present.index(color)
+    end
+
+    # Returns the palette as an array of [R, G, B] values.
+    #
+    # @return [Array]
+    def present
+      return @representation if @representation
+
+      red_mask, green_mask, blue_mask = 0x1f, 0x3e0, 0x7c00
+
+      in_bytes = to_bytes.dup
+      out_array = []
+
+      until in_bytes.empty?
+        color = Bytestream.from_bytes(in_bytes.slice!(0, 2).reverse).to_i
+
+        out_array << [
+          (color & red_mask) << 3,
+          (color & green_mask) >> 5 << 3,
+          (color & blue_mask) >> 10 << 3
+        ]
+      end
+
+      @representation = out_array
+    end
+
+    alias_method :to_a, :present
+
+    # Converts the internal representation to a GBA-compatible
+    # stream of bytes.
+    #
+    # @return [String]
+    # @see ByteOutput#generate_bytes
+    def generate_bytes
+      pal = ''
+      @representation.each do |c|
+        red = c[0] >> 3
+        green = c[1] >> 3 << 5
+        blue = c[2] >> 3 << 10
+
+        pal <<
+          Bytestream.from_hex(format('%04X', (blue | green | red))).to_b.reverse
+      end
+
+      pal.rjust(2 * @representation.length, "\x00")
+    end
+
+    # A blurb showing the color count of the palette.
+    #
+    # @return [String]
+    def to_s
+      "Palette (#{present.length})"
+    end
+  end
+end

data/lib/sabrina/plugin.rb

@@ -0,0 +1,145 @@
+module Sabrina
+  # This is the recommended wrapper namespace for {Plugin Plugins} that enhance
+  # {Sabrina} with new functionality.
+  #
+  # @see Plugin
+  module Plugins; end
+
+  # The base class for plugins that improve classes with the ability
+  # to handle additional data. The +#initialize+ method for every
+  # plugin should accept a target class instance as the parameter.
+  # The +#initialize+ method of the target class should contain
+  # a call to +load_plugins+.
+  #
+  # When a class has been enhanced by a plugin, it will gain a read-only
+  # attribute +#plugins+ that will contain a set of all plugins registered
+  # with that class. Class instances will gain a read-only attribute
+  # +#plugins+ that will contain a hash of SHORT_NAME => (plugin instance)
+  # pairs.
+  #
+  # Each plugin will also expose a set of {FEATURES}. For every +feature+, two
+  # instance methods will be added to the target object: +#feature+, which
+  # will call +#feature+ on every plugin instance that supports it, and
+  # +#feature_shortname+, which will call +#feature+ on the instance of the
+  # plugin identified by {SHORT_NAME} (assuming it supports that feature).
+  #
+  # For clarity, plugins should be contained within the {Plugins}
+  # namespace.
+  class Plugin
+    # What class this plugin enhances. This should be required before
+    # the plugin.
+    #
+    # The target class should have +load_plugins+ at the end of the init.
+    ENHANCES = Monster
+
+    # Plugin name goes here.
+    PLUGIN_NAME = 'Generic Plugin'
+
+    # Short name should contain only a-z, 0-9, and underscores.
+    # This will be the suffix for target instance methods.
+    SHORT_NAME = 'genericplugin'
+
+    # Tells the enhanced class what public instance methods the plugin
+    # should expose.
+    #
+    # This should be a set of symbols.
+    #
+    # Common features include +:reread+, +:write+, +:save+, +:load+.
+    FEATURES = Set.new [:reread, :write, :save, :load]
+
+    class << self
+      # @see PLUGIN_NAME
+      def plugin_name
+        self::PLUGIN_NAME
+      end
+
+      # @see ENHANCES
+      def target
+        self::ENHANCES
+      end
+
+      # @see SHORT_NAME
+      def short_name
+        self::SHORT_NAME.downcase.gsub(/[^a-z0-9_]/, '')
+      end
+
+      # @see FEATURES
+      def features
+        self::FEATURES
+      end
+
+      # Automagically registers new plugins with target.
+      def inherited(subclass)
+        target.extend(Plugin::Register)
+        Plugin::Load.include_in(target)
+
+        target.register_plugin(subclass)
+        super
+      end
+
+      # Generate a +#feature+ method.
+      #
+      # @param [Symbol] f feature.
+      # @return [Proc]
+      def feature_all(f)
+        proc do |*args|
+          targets = @plugins.select { |_key, val| val.feature?(f) }
+          targets.values.map { |val| val.method(f).call(*args) }
+        end
+      end
+
+      # Generate a +#feature_shortname+ method.
+      #
+      # @param [Symbol] f feature.
+      # @return [Proc]
+      def feature_this(f, n)
+        proc do |*args|
+          @plugins.fetch(n).method(f).call(*args)
+        end
+      end
+
+      # Provides a short description of the plugin's functionality.
+      #
+      # @return [String]
+      def to_s
+        "\'#{short_name}\': enhances #{target.name}, supports #{features.to_a}"
+      end
+    end
+
+    # Generates a new {Plugin} object.
+    #
+    # @param [Object] parent
+    # @return [Plugin]
+    def initialize(parent, *_args)
+      @parent = parent
+    end
+
+    # Drop internal data and force reloading from ROM.
+    #
+    # @return [Array] Any return data from child methods.
+    def reread(*_args)
+      children.map(&:reload_from_rom)
+    end
+
+    # Write data to ROM.
+    #
+    # @return [Array] Any return data from child methods.
+    def write(*_args)
+      children.map(&:write_to_rom)
+    end
+
+    # Whether a plugin instance supports a feature.
+    #
+    # @return [Boolean]
+    def feature?(f)
+      self.class.features.include?(f)
+    end
+
+    # Subclasses should override this to provide a useful textual
+    # representation of instance data.
+    # @return [String]
+    def to_s
+      "<#{self.class.plugin_name}>"
+    end
+  end
+end