adventure_rl 0.0.1.pre.ld42

data/doc/Mask.md

@@ -0,0 +1,183 @@
+# `AdventureRL::Mask`
+The mask is a two dimensional area.  
+It has a `position`, `size`, and `origin`.
+
+The mask should make collision checking and the like easier.
+
+__Table of Contents__
+- [Methods](#methods)
+  - [`initialize`](#initialize)
+  - [`assign_to`](#assign_to)
+  - [`get_mask`](#get_mask)
+  - [`get_point`](#get_point)
+  - [`get_position`](#get_position)
+  - [`get_size`](#get_size)
+  - [`get_origin`](#get_origin)
+  - [`get_corner`](#get_corner)
+  - [`get_side`](#get_side)
+  - [`get_sides`](#get_sides)
+  - [`get_center`](#get_center)
+  - [`collides_with?`](#collides_with)
+
+## Methods
+### `initialize`
+```ruby
+def initialize args = {}
+end
+```
+The mask has the following attributes,  
+which should be passed as a hash on initialization:
+
+- `position`  
+  The starting position of the mask, relative to its `origin`.  
+  This can be a hash with the keys `x` and `y`, or a `AdventureRL::Point`.
+
+- `size`  
+  The size of the mask. It is passed as a hash with the keys  
+  `width` and `height`.
+
+- `origin`  
+  The origin of the mask is where the `position` is located on the mask.  
+  It is passed as a hash with the keys `x` and `y`, and their values can be:
+  - for `:x` - `:left`
+  - for `:x` - `:right`
+  - for `:y` - `:top`
+  - for `:y` - `:bottom`
+  - for `:x` or `:y` - `center`
+
+  Usually, if you only use the mask's methods, the origin position should be  
+  irrelevant to you, and you can ommit it. The only method which's output  
+  it effects, is `#get_position`, as it will give you the point you initially  
+  passed, which is the point where the origin position is.
+
+- `assign_to`  
+  You can pass any object as `assign_to`'s value. This will make it possible  
+  for the assigned object to have access to all of mask's methods directly.  
+  This defines a `#method_missing` method which pipes any missing methods to  
+  the mask. So you could _not_ create a reference to the mask _(no variable)_  
+  and just initialize the mask, assign your object, and it will have access  
+  to all of its mask's methods.
+
+If any or all of the above values are not passed, the defaults are used:
+```ruby
+{
+  position: {
+    x: 0,
+    y: 0
+  },
+  size: {
+    width:  64,
+    height: 64
+  },
+  origin: {
+    x: :left,
+    y: :top
+  },
+  assign_to: nil
+}
+```
+
+### `assign_to`
+```ruby
+def assign_to object
+end
+```
+Assigns the object to the mask. The same method is called if you pass  
+the `:assign_to` key with a object in `#initialize`.
+
+### `get_mask`
+```ruby
+def get_mask
+end
+```
+Returns self. Objects which this mask was assigned to _(see #initialize)_  
+have a way of getting the actual mask with this method.
+
+### `get_point`
+```ruby
+def get_point
+end
+```
+Returns the point with the positions passed to it initially.
+
+### `get_position`
+```ruby
+def get_position target = :all
+end
+```
+Returns its position, same as `get_point.get_position`.
+
+### `get_size`
+```ruby
+def get_size target = :all
+end
+```
+Returns its size, similar to `#get_position`,  
+only with its sides, `width` and `height`.
+
+### `get_origin`
+```ruby
+def get_origin
+end
+```
+Returns its size, similar to `#get_position`,  
+only with its origin axes, `x` and `y`.
+
+### `get_corner`
+```ruby
+def get_corner side_x, side_y
+end
+```
+Returns a point with the corner position of the given `side_x` and `side_y`.  
+For example:
+```ruby
+mask = AdventureRL::Mask.new( ... )
+mask.get_corner :left, :top       # => Returns point with top-left corner position.
+mask.get_corner :right, :bottom   # => Returns point with botton-right corner position.
+mask.get_corner :center, :center  # => Returns center point - same 
+```
+
+### `get_side`
+```ruby
+def get_side target
+end
+```
+Returns an integer of the axis for the given target side.  
+For example:
+```ruby
+mask = AdventureRL::Mask.new( ... )
+mask.get_side :left  # => Returns x axis of the left mask edge.
+mask.get_side :top   # => Returns y axis of the top mask edge.
+```
+
+### `get_sides`
+```ruby
+def get_sides
+end
+```
+Returns a hash with all side positions. Example return value:
+```ruby
+{
+  left:   10,
+  right:  60,
+  top:    20,
+  bottom: 70
+}
+```
+
+### `get_center`
+```ruby
+def get_center target = :all
+end
+```
+If target is `:all`, returns a new point with the center position of the mask.  
+Otherwise, if target is `:x` or `:y`, returns an integer representing  
+the center of the target's axis.
+
+### `collides_with?`
+```ruby
+def collides_with? point_or_mask
+end
+```
+This method checks if it is in collision / overlapping with  
+a `AdventureRL::Point` or `Adventure::Mask`; the argument accepts both.

data/doc/Point.md

@@ -0,0 +1,95 @@
+# `AdventureRL::Point`
+A point is a two dimensional vector.  
+it has an `x` axis and a `y` axis.  
+It should be pretty straight-forward and self-explanatory.
+
+__Table of Contents__
+- [Methods](#methods)
+  - [`initialize`](#initialize)
+  - [`assign_to`](#assign_to)
+  - [`get_point`](#get_point)
+  - [`x`](#x)
+  - [`y`](#y)
+  - [`get_position`](#get_position)
+  - [`set_position`](#set_position)
+  - [`collides_with?`](#collides_with)
+  - [`keys`](#keys)
+  - [`values`](#values)
+
+## Methods
+### `initialize`
+```ruby
+def initialize x, y, args = {}
+end
+```
+Create a new point with `x` and `y` axes.  
+You can pass the key `:assign_to` with the value of an object with args  
+to make all point methods available directly through the object.
+
+### `assign_to`
+```ruby
+def assign_to object
+end
+```
+Assigns the object to the point.  
+Same as using the key `:assign_to` in `#initialize`.
+
+### `get_point`
+```ruby
+def get_point
+end
+```
+Returns self.  
+Useful for using from objects where the point was assigned to them.
+
+### `x`
+```ruby
+def x
+end
+```
+Returns the integer for its `x` axis.
+
+### `y`
+```ruby
+def y
+end
+```
+Returns the integer for its `y` axis.
+
+### `get_position`
+```ruby
+def get_position target = :all
+end
+```
+Returns either both axes as a hash if target is `:all` or is ommited,  
+or returns the value of target's axis.
+
+### `set_position`
+```ruby
+def set_position
+end
+```
+
+### `collides_with?`
+```ruby
+def collides_with? point_or_mask
+end
+```
+This method checks if it is in collision / overlapping with  
+a `AdventureRL::Point` or `Adventure::Mask`; the argument accepts both.
+
+### `keys`
+```ruby
+def keys
+end
+```
+Returns the symbols `:x` and `:y` in an array, respectively.  
+Based on `Hash#keys`.
+
+### `values`
+```ruby
+def values
+end
+```
+Returns the `:x` and `:y` axes in an array, respectively.  
+Based on `Hash#values`.

data/doc/Window.md

@@ -0,0 +1,139 @@
+# `AdventureRL::Window`
+This class inherits from `Gosu::Window`.  
+It is responsible for the actual window updating and drawing.
+
+__Table of Contents__
+- [Methods](#methods)
+  - [`initialize`](#initialize)
+  - [`setup`](#setup)
+  - [`get_fps`](#get_fps)
+  - [`get_deltatime`](#get_deltatime)
+  - [`get_tick`](#get_tick)
+- [Gosu Methods](#gosu-methods)
+  - [`update` and `draw`](#update-and-draw)
+- [Example Window Initialization](#example-window-initialization)
+
+## Methods
+### `initialize`
+```ruby
+def initialize args = {}
+end
+```
+Unlike with Gosu, the `#initialize` method should _not_ be overwritten.  
+Instead, define the method `#setup`, which will be called after `#initialize`.  
+You should pass a hash of settings to `#initialize`,  
+which will also be passed to `#setup`, if `#setup` takes an argument.  
+An example hash for `args`:
+```ruby
+AdventureRL::Window.new({
+  size: {
+    width:  960,
+    height: 540
+  },
+  caption: 'My AdventureRL Game!'
+})
+```
+You can pass anything you want in the hash and use it in your `#setup` method.  
+For any mandatory hashes you don't pass _(such as `:size`)_ the defaults  
+will be used, which is defined in the gem's root in `default_settings.yml`.
+
+### `setup`
+```ruby
+def setup args
+end
+```
+As mentioned above, this method is supposed to be overwritten by the developer.  
+It will be called after `#initialize` has finished.  
+You do not have to define it with taking an argument, but if you don't  
+the arguments you passed to `#initialize` (`.new`) will not be available to you  
+in `#setup`.
+
+### `get_fps`
+```ruby
+def get_fps
+end
+```
+Returns current frame rate. This is just a wrapper method for `Gosu.fps`.  
+I decided to add this just to follow the design pattern with `get_*` methods.
+
+### `get_deltatime`
+```ruby
+def get_deltatime
+end
+```
+This method returns a float, representing the time difference in seconds  
+to the last call to update. Using deltatime you can prevent your game from  
+running at a different speed on slower computers.  
+Read more about __deltatime__ at [gamedev.stackexchange.com][gamedev-deltatime-url].
+
+### `get_tick`
+```ruby
+def get_tick
+end
+```
+This method returns an integer, which is increased by one  
+everytime `#update` is called. __*__
+
+> __Attention__  
+> Methods marked with an asterisk _(*)_ are only available  
+> if you call `super` at the end of `#update`.
+
+## Gosu Methods
+The following methods come from the gosu gem's `Gosu::Window` class,  
+as `AdventureRL::Window` inherits from `Gosu::Window`,  
+all of gosu's window methods are available to you.  
+Here are some examples of useful/necessary `Gosu::Window` methods.
+
+### `update` and `draw`
+```ruby
+def update
+  # This method is called every frame.
+  # You're supposed to do handle any calculations your game does here,
+  # such as player movement, mouse clicks, etc.
+end
+def draw
+  # This method is also called every frame, after the #update method.
+  # Here, you are supposed to handle the drawing of your images, textures, etc.
+end
+```
+You should call `super` at the end of `#update`.  
+If you don't, you will not be able to use a lot of methods  
+and features provided by AdventureRL, such as `#get_deltatime` or `#get_tick`.
+
+Check out [Gosu's documentation][gosu-window-doc] for a list of available methods.
+
+## Example Window Initialization
+```ruby
+class MyGame < AdventureRL::Window
+  def setup args
+    self.caption = 'I prefer this window title!'
+    @my_settings = AdventureRL::Settings.new 'path/to/my_settings.yml'
+    @font = Gosu::Font.new 24
+    # ...
+  end
+
+  private
+
+  def update
+    puts "Current tick: #{get_tick}"  # Prints the current tick to stdout.
+    super  # Call the parent's #update method to have access to a lot of useful methods.
+  end
+
+  def draw
+    center_point = get_center
+    @font.draw_rel(
+      "Delta-Time:\n#{get_deltatime}",
+      center_point.x, center_point.y, 0,
+      0.5, 0.5, 1, 1,
+      0xff_00ff00
+    )
+  end
+end
+
+my_game = MyGame.new
+my_game.show  # Actually open and render the window
+              # and start your game loops #update and #draw.
+```
+
+[gamedev-deltatime-url]: https://gamedev.stackexchange.com/questions/1589/when-should-i-use-a-fixed-or-variable-time-step
+[gosu-window-doc]:       https://www.rubydoc.info/github/gosu/gosu/Gosu/Window

data/lib/AdventureRL/Animation.rb

@@ -0,0 +1,63 @@
+module AdventureRL
+  class Animation < Image
+    DEFAULT_SETTINGS = Settings.new(
+      files:     ['DEFAULT_ANIMATION_FILE.png'],
+      intervals: [0.5]  # Image switch intervals in seconds.
+    )
+
+    def initialize settings = {}
+      @settings = DEFAULT_SETTINGS.merge settings
+      image_settings = @settings.get
+      image_settings[:dont_create_image] = true
+      super image_settings
+      @images              = get_images_from [@settings.get(:files)].flatten
+      @animation_intervals = [@settings.get(:intervals)].flatten
+      @timing_handler      = TimingHandler.new
+      @timeout_id          = :next_image_timeout
+      @current_image_index = -1
+      next_image
+    end
+
+    def update_animation
+      @timing_handler.update
+    end
+
+    # Call this (or #update_animation) every frame, to ensure that the animation is playing.
+    def update
+      update_animation
+    end
+
+    def next_image
+      @current_image_index += 1
+      @current_image_index  = 0  if (@current_image_index >= @images.size)
+      @image = @images[@current_image_index]
+      set_timeout
+    end
+
+    def set_timeout
+      current_interval = get_current_interval
+      @timing_handler.set_timeout(
+        id:      @timeout_id,
+        seconds: get_current_interval,
+        method:  method(:next_image)
+      )  if (current_interval)
+    end
+
+    private
+
+      def get_images_from files
+        return files.map do |file|
+          next get_image_from(file)
+        end
+      end
+
+      def get_current_interval
+        intervals_size = @animation_intervals.size
+        if (@current_image_index < intervals_size)
+          return @animation_intervals[@current_image_index]
+        else
+          return @animation_intervals[@current_image_index - (intervals_size * (@current_image_index / intervals_size).floor)]
+        end
+      end
+  end
+end

data/lib/AdventureRL/Audio.rb

@@ -0,0 +1,75 @@
+module AdventureRL
+  class Audio < FileGroup
+    AUDIO_FILENAME_REGEX = /\A\d+\.(flac|wav|ogg)\z/i
+    INTERNAL_DEFAULT_SETTINGS = Settings.new({
+      name:      :audio_name,
+      directory: nil,
+      fps:       24,
+      volume:    1.0
+    })
+    @@default_settings = nil
+    @@root_directory   = Pathname.new($0).dirname
+
+    class << self
+      # Set the root directory for the audio files directory.
+      # All settings 'directory' values will be relative to this.
+      # Defaults to the entry scripts (the script that was called, <tt>$0</tt>) directory.
+      # Pass either a String with the directory path, or an instance of Pathname.
+      def set_root_directory directory
+        directory = Pathname.new directory  unless (directory.is_a? Pathname)
+        @@root_directory = Pathname.new directory
+      end
+      alias_method :root=, :set_root_directory
+
+      # Returns the currently set root audio files directory.
+      def get_root_directory
+        return @@root_directory
+      end
+      alias_method :root, :get_root_directory
+
+      # Set the default Settings.
+      # Pass either String to a YAML settings file,
+      # or a Hash with your default settings.
+      def set_default_settings settings
+        default_settings = nil
+        if    ([String, Pathname].include? settings.class)
+          filepath = settings
+          filepath = Pathname.new filepath  unless (filepath.is_a? Pathname)
+          if (filepath.absolute?)
+            default_settings = Settings.new filepath
+          else
+            if (File.file?(filepath))
+              default_settings = Settings.new filepath
+            else
+              default_settings = Settings.new get_root_directory.join(filepath)
+            end
+          end
+        elsif (settings.is_a? Hash)
+          default_settings = Settings.new settings
+        end
+        @@default_settings = default_settings
+      end
+      alias_method :default_settings=, :set_default_settings
+    end
+
+
+    # Initialize with either a path to a YAML settings file as a String,
+    # or a Hash containing your settings.
+    def initialize settings
+      super
+    end
+
+    private
+
+      # Returns this class' specific INTERNAL_DEFAULT_SETTINGS.
+      def get_default_settings
+        return INTERNAL_DEFAULT_SETTINGS.merge @@default_settings  if (@@default_settings)
+        return INTERNAL_DEFAULT_SETTINGS
+      end
+
+      # Should return the regex which must match the filenames.
+      def get_filename_regex
+        return AUDIO_FILENAME_REGEX
+      end
+  end
+end

data/lib/AdventureRL/AudioPlayer.rb

@@ -0,0 +1,65 @@
+module AdventureRL
+  class AudioPlayer < FileGroupPlayer
+    # Default settings for AudioPlayer.
+    # Are superseded by settings passed to #new.
+    DEFAULT_SETTINGS = Settings.new({
+      speed:     1.0,
+      loop:      false,
+      max_speed: 10.0
+    })
+
+    # Pass settings Hash or Settings as argument.
+    # Supersedes DEFAULT_SETTINGS.
+    def initialize settings = {}
+      super
+    end
+
+    # Returns the currently active Audio.
+    # Wrapper for FileGroupPlayer#get_filegroup
+    alias_method :get_audio, :get_filegroup
+
+    # Overwrite FileGroupPlayer#update to set
+    # a max speed limit. Don't play anymore once
+    # it it greater than the max speed.
+    # <tt>:max_speed</tt> can be passed to #new,
+    # to overwrite the default.
+    def update
+      return  if (above_max_speed?)
+      super
+    end
+
+    private
+
+      # Returns true if the current playback speed is
+      # above the max speed limit.
+      def above_max_speed?
+        return get_speed > get_settings(:max_speed)
+      end
+
+      # (Stops the last audio file,) -- Gosu cannot stop a Gosu::Sample, and that's what we're using.  
+      # Loads the new audio file <tt>file</tt>,
+      # and play it right away.
+      def load_file file
+        get_current_channel.stop  if (get_current_channel)
+        sample = Gosu::Sample.new(file)
+        set_current_channel sample.play(
+          get_audio.get_settings(:volume),
+          @speed,
+          !:loop
+        )
+      end
+
+      # Returns this class' DEFAULT_SETTINGS.
+      def get_default_settings
+        return DEFAULT_SETTINGS
+      end
+
+      # Returns the current Gosu::Channel.
+      # Wrapper for FileGroupPlayer#get_current_file
+      alias_method :get_current_channel, :get_current_file
+
+      # Set a new current Gosu::Channel.
+      # Wrapper for FileGroupPlayer#set_current_file
+      alias_method :set_current_channel, :set_current_file
+  end
+end

data/lib/AdventureRL/Button.rb

@@ -0,0 +1,51 @@
+module AdventureRL
+  class Button < Textbox
+    DEFAULT_SETTINGS = Settings.new(
+      active_color:      0xff_cc8822,
+      hover_colow:       0xff_888888,
+      pressable:         false,
+      click_on_mouse_up: false
+    )
+
+    def initialize settings = {}
+      @settings = DEFAULT_SETTINGS.merge settings
+      super @settings
+      @colors = {
+        active: @settings.get(:active_color),
+        hover:  @settings.get(:hover_colow),
+      }
+      @pressable         ||= @settings.get :pressable
+      @click_on_mouse_up ||= @settings.get :click_on_mouse_up
+      @click_on_mouse_up ||= false  if (@pressable)
+    end
+
+    def get_menu
+      layer = get_layer
+      return layer  if (layer.is_a? Menu)
+      return nil
+    end
+
+    def on_mouse_down
+      return  if (is_pressable?)
+      set_color @colors[:active]
+      click  if (!@click_on_mouse_up && methods.include?(:click))
+    end
+
+    def on_mouse_up
+      return  if (is_pressable?)
+      reset_color
+      click  if (@click_on_mouse_up && methods.include?(:click))
+    end
+
+    def on_mouse_press
+      return  unless (is_pressable?)
+      set_temporary_color @colors[:active]
+    end
+
+    private
+
+      def is_pressable?
+        return !!@pressable
+      end
+  end
+end