metro 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,6 @@
 # metro
 
-Metro is a framework built around [gosu](https://github.com/jlnr/gosu) the 2D game development library in Ruby. The goal of Metro is to enforce common conceptual structures and conventions making it easier to quickly generate a game.
+Metro is a framework built around [gosu](https://github.com/jlnr/gosu) (the 2D game development library in Ruby). The goal of Metro is to enforce common conceptual structures and conventions making it easier to quickly generate a game.
 
 > NOTE: This project is very early in development and at this point mostly a prototype to explore more of theses concepts to gain an understanding of core tools necessary to make games.
 

data/lib/metro/event_relay.rb

@@ -1,56 +1,225 @@
 module Metro
-  class EventRelay
-
-    attr_reader :target, :window
 
-    attr_reader :up_actions, :down_actions, :held_actions
+  #
+  # An EventRelay represents a target's willingness to respond to events
+  # generate from the window. An event relay is generate for every scene
+  # but additional relays can be generated to also listen for events.
+  #
+  # An event relay can register a target to listen for the following window
+  # events: 'button_down'; 'button_up'; and 'button_held'.
+  #
+  # @note registering for 'button_held' events require that the window be
+  #   speicfied. As that is the only way to ask if the button is currently
+  #   pressed.
+  #
+  # @see #on_up
+  # @see #on_down
+  # @see #on_hold
+  #
+  # A target can also receive events when 'button_up' and 'button_down' events
+  # have been fired but did not map to any specified actions. This is similar to
+  # Ruby's {#method_missing}.
+  #
+  # To receive unampped 'button_up' events define a method
+  # named `up_action_missing(id)` within your target.
+  #
+  # To receive unampped 'button_down' events define a method
+  # named `down_action_missing(id)` within your target.
+  #
+  # @example Scene that receives all the 'button_up' and 'button_down' events that
+  #   are not mapped to actions.
+  #
+  #     class ExampleScene
+  #       def up_action_missing(id)
+  #         puts "No up action found for #{id}"
+  #       end
+  #
+  #       def down_action_missing(id)
+  #         puts "No down action found for #{id}"
+  #       end
+  #     end
+  #
+  class EventRelay
 
-    def initialize(target,window)
+    #
+    # An event relay is created a with a target and optionally a window.
+    #
+    # @param [Object] target the object that will execute the code when
+    #   the button events have fired have been triggered.
+    # @param [Window] window the window of the game. This parameter is
+    #   optional and only required if the events are interested in buttons
+    #   being held.
+    #
+    def initialize(target,window = nil)
       @target = target
       @window = window
-      @up_actions ||= Hash.new(:_no_action)
-      @down_actions ||= Hash.new(:_no_action)
-      @held_actions ||= Hash.new(:_no_action)
+      @up_actions ||= {}
+      @down_actions ||= {}
+      @held_actions ||= {}
     end
 
-    def on(hash,args,block)
-      options = (args.last.is_a?(Hash) ? args.pop : {})
+    attr_reader :target, :window
 
-      args.each do |keystroke|
-        hash[keystroke] = block || lambda { |instance| send(options[:do]) }
-      end
+    #
+    # Register for a button_down event. These events are fired when
+    # the button is pressed down. This event only fires once when the
+    # button moves from the not pressed to the down state.
+    #
+    # @example Registering for a button down event to call a method named 'previous_option'
+    #
+    #     class ExampleScene
+    #       def events(e)
+    #         e.on_down Gosu::GpLeft, Gosu::GpUp, do: :previous_option
+    #       end
+    #
+    #       def previous_option
+    #         @selected_index = @selected_index - 1
+    #         @selected_index = options.length - 1 if @selected_index <= -1
+    #       end
+    #     end
+    #
+    # Here in this scene if the GpLeft or GpUp buttons are pressed down the method
+    # `previous_options` will be executed.
+    #
+    #
+    # @example Registering for a button down event with a block of code to execute
+    #
+    #     class ExampleScene
+    #       def events(e)
+    #         e.on_down Gosu::GpLeft, Gosu::GpUp do
+    #           @selected_index = @selected_index - 1
+    #           @selected_index = options.length - 1 if @selected_index <= -1
+    #         end
+    #       end
+    #     end
+    #
+    # This example uses a block instead of a method name but it is absolultey the same
+    # as the last example.
+    #
+    def on_down(*args,&block)
+      _on(@down_actions,args,block)
     end
 
+    #
+    # Register for a button_up event. These events are fired when
+    # the button is released (from being pressed down). This event only fires
+    # once when the button moves from the pressed state to the up state.
+    #
+    # @example Registering for a button down event to call a method named 'next_option'
+    #
+    #     class ExampleScene
+    #       def events(e)
+    #         e.on_up Gosu::KbEscape, do: :leave_scene
+    #       end
+    #
+    #       def leave_scene
+    #         transition_to :title
+    #       end
+    #     end
+    #
+    # Here in this scene if the Escape Key is pressed and released the example scene
+    # will transition to the title scene.
+    #
+    # @example Registering for a button up event with a block of code to execute
+    #
+    #     class ExampleScene
+    #       def events(e)
+    #         e.on_up Gosu::KbEscape do
+    #           transition_to :title
+    #         end
+    #       end
+    #     end
+    #
+    # This example uses a block instead of a method name but it is absolultey the same
+    # as the last example.
+    #
     def on_up(*args,&block)
-      on(@up_actions,args,block)
+      _on(@up_actions,args,block)
     end
 
-    def on_down(*args,&block)
-      on(@down_actions,args,block)
+    #
+    # Register for a button_held event. These events are fired when
+    # the button is currently in the downstate. This event continues to fire at the
+    # beginning of every update of a scene until the button is released.
+    #
+    # @note button_held events require that the window be specified during initialization.
+    #
+    # @example Registering for button held events
+    #
+    #     class ExampleScene
+    #       def events(e)
+    #         e.on_hold Gosu::KbLeft, Gosu::GpLeft do
+    #           player.turn_left
+    #         end
+    #
+    #         e.on_hold Gosu::KbRight, Gosu::GpRight do
+    #           player.turn_right
+    #         end
+    #
+    #         e.on_hold Gosu::KbUp, Gosu::GpButton0, do: :calculate_accleration
+    #       end
+    #
+    #       def calculate_acceleration
+    #         long_complicated_calculated_result = 0
+    #         # ... multi-line calculations to determine the player acceleration ...
+    #         player.accelerate = long_complicated_calculated_result
+    #       end
+    #     end
+    #
+    def on_hold(*args,&block)
+      log.warn "Registering for a on_hold event requires that a window be provided." unless window
+      _on(@held_actions,args,block)
     end
 
-    def on_hold(*args,&block)
-      on(@held_actions,args,block)
+    attr_reader :up_actions, :down_actions, :held_actions
+
+    def _on(hash,args,block)
+      options = (args.last.is_a?(Hash) ? args.pop : {})
+
+      args.each do |keystroke|
+        hash[keystroke] = block || lambda { |instance| send(options[:do]) }
+      end
     end
 
+    #
+    # This is called by external or parent source of events, usually a Scene, when a button up event
+    # has been triggered.
+    #
     def button_up(id)
-      action = up_actions[id]
-      target.instance_eval(&action)
+      target.instance_eval( &up_action(id) )
+    end
+
+    #
+    # This is called by external or parent source of events, usually a Scene, when a button down
+    # event has been triggered.
+    #
+    def button_down(id)
+      target.instance_eval( &down_action(id) )
     end
 
-    def trigger_held_buttons
+    #
+    # Fire the events mapped to the held buttons within the context
+    # of the specified target. This method is differently formatted because held buttons are not
+    # events but polling to see if the button is still being held.
+    #
+    def fire_events_for_held_buttons
       held_actions.each do |key,action|
-        target.instance_eval(&action) if window.button_down?(key)
+        target.instance_eval(&action) if window and window.button_down?(key)
       end
     end
 
-    def button_down(id)
-      down_actions.each do |key,action|
-        if window.button_down?(key)
-          target.instance_eval(&action)
-        end
-      end
+    # @return a block of code that is mapped for the 'button_up' id or a block that will attempt to call out
+    #   to the action missing method.
+    def up_action(id)
+      up_actions[id] || lambda {|instance| send(:up_action_missing,id) if respond_to?(:up_action_missing) }
     end
 
+    # @return a block of code that is mapped for the 'button_down' id or a block that will attempt to call out
+    #   to the action missing method.
+    def down_action(id)
+      down_actions[id] || lambda {|instance| send(:down_action_missing,id) if respond_to?(:down_action_missing) }
+    end
+
+
   end
 end

data/lib/metro/game/dsl.rb

@@ -9,7 +9,7 @@ module Metro
       end
 
       def first_scene(scene_name = nil)
-        scene_name ? @first_scene = Scenes.find(scene_name) : @first_scene
+        scene_name ? @first_scene = scene_name : @first_scene
       end
 
       def width(game_width = nil)
@@ -24,6 +24,10 @@ module Metro
         [ width(w), height(h) ]
       end
 
+      def fullscreen(set_fullscreen = nil)
+        set_fullscreen.nil? ? @fullscreen : @fullscreen = set_fullscreen
+      end
+
     end
   end
 end

data/lib/metro/game.rb

@@ -30,6 +30,10 @@ module Metro
       [ width / 2 , height / 2 ]
     end
 
+    def fullscreen?
+      !!config.fullscreen
+    end
+
     # TODO: ZOrder related constants that belong to Starry Knight
     Background, Stars, Players, UI = *0..3
 

data/lib/metro/scene.rb

@@ -1,5 +1,4 @@
 require_relative 'scene_view/scene_view'
-require_relative 'scene_view/components/drawer'
 require_relative 'event_relay'
 
 module Metro
@@ -21,133 +20,148 @@ module Metro
   class Scene
 
     #
-    # The window is the main instance of the game. Using window can access a lot of
-    # underlying Metro::Window, a subclass of Gosu::Window, that the Scene class is
-    # obfuscating.
+    # The events method is where a scene has access to configure the events that it
+    # would like to listen for during the scene.
     #
-    # @see Metro::Window
-    # @see Gosu::Window
+    # @note This method should be implemented in the Scene subclass.
     #
-    attr_reader :window
+    # @param [EventRelay] e is the EventRelay that you can register for button up,
+    #   button down, or button held events.
+    #
+    # @see EventRelay
+    #
+    def events(e) ; end
 
     #
-    # The events object that is configured through the {#events} method, which stores
-    # all the gamepad and keyboard events defined.
+    # This method is called right after the scene has been adopted by the window
     #
-    # @see Events
+    # @note This method should be implemented in the Scene subclass.
     #
-    attr_reader :event_relays
+    def show ; end
 
     #
-    # Customized views that contain elements to be drawn will be handled by the
-    # view_drawer.
+    # This is called every update interval while the window is being shown.
     #
-    # @see SceneView::Drawer
+    # @note This method should be implemented in the Scene subclass.
     #
-    attr_reader :view_drawer
+    def update ; end
 
     #
-    # Captures all classes that subclass Scene.
+    # This is called after every {#update} and when the OS wants the window to
+    # repaint itself.
     #
-    def self.inherited(base)
-      scenes << base
-    end
+    # @note This method should be implemented in the Scene subclass.
+    #
+    def draw ; end
 
     #
-    # All subclasses of Scene, this should be all the defined scenes
-    # within the game.
+    # Before a scene is transisitioned away from to a new scene, this method is called
+    # to allow for the scene to complete any taskss, stop any actions, or pass any
+    # information from the existing scene to the scene that is about to replace it.
     #
-    # @return an Array of Scene subclasses
+    # @note This method should be implemented in the Scene subclass.
     #
-    def self.scenes
-      @scenes ||= []
-    end
+    # @param [Scene] new_scene this is the instance of the scene that is about to replace
+    #   the current scene.
+    #
+    def prepare_transition(new_scene) ; end
 
-    # This provides the functionality for view handling.
-    include SceneView
+    #
+    # The window is the main instance of the game. Using window can access a lot of
+    # underlying Metro::Window, a subclass of Gosu::Window, that the Scene class is
+    # obfuscating.
+    #
+    # @see Metro::Window
+    # @see Gosu::Window
+    #
+    attr_reader :window
 
     #
-    # A scene is created with a window instance. When subclassing a Scene, you should
-    # hopefully not need to create an {#initialize} method or call `super` but instead
-    # implement the {#show} method which is the point of incision in the subclasses
-    # that allow for the subclasses of Scene to be setup correctly.
+    # Setting the window places the scene within in the specified window. Which
+    # will cause a number of variables and settings to be set up. The {#show}
+    # method is called after the window has been set.
     #
-    def initialize(window)
+    def window=(window)
       @window = window
 
-      @event_relays ||= []
+      @event_relays = []
 
       @scene_events = EventRelay.new(self,window)
       events(@scene_events)
 
       @event_relays << @scene_events
 
-      @view_drawer = SceneView::Drawer.new(self)
-
       show
     end
 
     #
-    # This method should be defined in the Scene subclass.
+    # Allows you to set or retrieve the scene name for the Scene.
     #
-    # @param [Events] e is the object that you can register button presses
+    # @example Retrieving the default scene name
     #
-    def events(e) ; end
-
-    def add_event_relay(event_relay)
-      @event_relays << event_relay
-    end
-
-    def trigger_held_buttons
-      event_relays.each do |er|
-        er.trigger_held_buttons
-      end
-    end
-
-    def button_up(id)
-      event_relays.each do |er|
-        er.button_up(id)
-      end
+    #     class ExampleScene
+    #       def show
+    #         puts "Showing Scene: #{self.class.scene_name}"
+    #       end
+    #     end
+    #
+    #     ExampleScene.scene_name
+    #
+    # @example Setting a custom name for the Scene
+    #
+    #     class RollingCreditsScene
+    #       scene_name "credits"
+    #     end
+    #
+    # @param [String] scene_name when specified it will set the scene name for the class
+    #   to the value specified.
+    #
+    # @return the String name of the scene which it can be used as a reference for transitioning
+    #   or for generating the appropriate view information.
+    #
+    def self.scene_name(scene_name=nil)
+      @scene_name ||= to_s[/^(.+)Scene$/,1].downcase
+      scene_name ? @scene_name = scene_name.to_s : @scene_name
     end
 
-    def button_down(id)
-      event_relays.each do |er|
-        er.button_down(id)
-      end
+    #
+    # @return the string representation of a scene, this is used for debugging.
+    #
+    def to_s
+      "[SCENE: #{self.class.scene_name}(#{self.class})]"
     end
 
     #
-    # This method is solely a non-action method for when events are triggered
-    # for button up and button down
+    # Captures all classes that subclass Scene.
     #
-    def _no_action ; end
-
-    # This method is called right after initialization
-    def show ; end
+    # @see #self.scenes
+    #
+    def self.inherited(base)
+      scenes << base
+    end
 
     #
-    # This method handles the logic or game loop for the scene.
+    # All subclasses of Scene, this should be all the defined scenes within the game.
     #
-    # @note This method should be implemented in the subclassed Scene
+    # @return an Array of Scene subclasses
     #
-    def update ; end
+    def self.scenes
+      @scenes ||= []
+    end
 
     #
-    # The `_draw` method is called by the Game Window to allow for any view related
+    # The `base_draw` method is called by the Game Window. This is allow for any special
     # drawing needs to be handled before calling the traditional `draw` method defined
-    # in the subclassed Scenes.
+    # in the subclassed Scene.
     #
-    def _draw
-      view_drawer.draw(view)
+    def base_draw
       draw
     end
 
-    #
-    # This method handles all the visual rendering of the scene.
-    #
-    # @note This method should be implemented in the subclassed Scene
-    #
-    def draw ; end
+    # This provides the functionality for view handling.
+    # @note the inclusion of view functionality redefines {#base_draw} so it must proceed
+    #   the declaration of that method.
+    include SceneView
 
     #
     # `transition_to` performs the work of transitioning this scene
@@ -157,7 +171,7 @@ module Metro
     #   the class or a string/symbol representation of the shortened scene name.
     #
     def transition_to(scene_name)
-      new_scene = Scenes.create(scene_name,window)
+      new_scene = Scenes.generate(scene_name)
       _prepare_transition(new_scene)
       window.scene = new_scene
     end
@@ -177,16 +191,55 @@ module Metro
     end
 
     #
-    # Before a scene is transisitioned away from to a new scene, this method is called
-    # to allow for the scene to complete any taskss, stop any actions, or pass any
-    # information from the existing scene to the scene that is about to replace it.
+    # The events object that is configured through the {#events} method, which stores
+    # all the gamepad and keyboard events defined. By default a scene has an event
+    # relay defined. Additional relays can be defined based on the components added.
     #
-    # @note This method should be implemented in the subclassed Scene
+    # @see Events
+    # @see #add_event_relay
     #
-    # @param [Scene] new_scene this is the instance of the scene that is about to replace
-    #   the current scene.
+    attr_reader :event_relays
+
     #
-    def prepare_transition(new_scene) ; end
+    # Add an additional event relay to the list of event relays. It is appended
+    # to the end of the list of relays.
+    #
+    # @param [EventRelay] event_relay an event relay instance that will now
+    #   receive events generated from this scene.
+    #
+    def add_event_relay(event_relay)
+      @event_relays << event_relay
+    end
+
+    #
+    # This method is called during a scene update and will fire all the events
+    # that have been defined for all held buttons for all defined event relays.
+    #
+    def fire_events_for_held_buttons
+      event_relays.each do |relay|
+        relay.fire_events_for_held_buttons
+      end
+    end
+
+    #
+    # This method is called before a scene update and passes the button up events
+    # to each of the defined event relays.
+    #
+    def button_up(id)
+      event_relays.each do |relay|
+        relay.button_up(id)
+      end
+    end
+
+    #
+    # This method is called before a scene update and passes the button down events
+    # to each of the defined event relays.
+    #
+    def button_down(id)
+      event_relays.each do |relay|
+        relay.button_down(id)
+      end
+    end
 
   end
 end

data/lib/metro/scene_view/drawers/artists_block.rb

@@ -0,0 +1,17 @@
+module Metro
+  module SceneView
+
+    #
+    # This Drawer draws nothing. This is a nod to the age old struggle that
+    # as artists we struggle with the impetus and ability to convey a message
+    # but simply lack the message.
+    #
+    # It is the fallback drawer when no suitable drawer can be found.
+    #
+    class ArtistsBlock < Drawer
+      def self.draw(view)
+        # log.warn "The component #{view['type']} does not have a supported drawer."
+      end
+    end
+  end
+end