gosling 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e286ba691604561ac6676e60e49699cd3167587
-  data.tar.gz: 6e2083451057aa524bed3f13012134e829a55f80
+  metadata.gz: ea892a020a95cbff0d56b2410eed22dcdffa0816
+  data.tar.gz: 9ad565fa00e58440ad245ec0ceae7479ab6c3900
 SHA512:
-  metadata.gz: 6232f177ad08bc4869af947c3c6748c004a052d47ca92247a8d0c54910117a6c8984aa5c5d7d35edb109e31ca5281536fc52c5013928b43bdd958e5edb1c6c44
-  data.tar.gz: 35fe442a079c785663f73640b006171c57872fe0c189bf55c9aa1146fd88c336f4cdabf52db410f3a84361fa862081dff505391c563e9f1f80e16729f1514a5f
+  metadata.gz: c45e93330e44318c58d2a76456d836366d7a9dc77ecd2c70ab08c1762ac6d92ca5cd20f257c367212759c03703e0387d7809ba08e88f48a3e3f7ecf8fa0ad500
+  data.tar.gz: 4711c9d648c83e8d26b5dfdf7b2bd7266db076500ad21c85ad8b1669fe26785efaf7294a48f6865609ee2f5d4f6b93e8256f7ac926686990cfdde2db41d308ea

data/lib/gosling/actor.rb

@@ -3,10 +3,70 @@ require_relative 'transform.rb'
 require 'gosu'
 
 module Gosling
+  ##
+  # Actors are fundamental elements of a rendering and worldspace hierarchy. They represent the things that exist
+  # inside of the game world or parts of our application's user interface.
+  #
+  # A key difference between an Actor and any of its subclasses - Circle, Polygon, Sprite, and the like - is that an
+  # Actor is inherently intangible. By itself, it has no shape or appearance and takes up no space. If it's something you
+  # can see or interact with, it should probably be an instance of one of Actor's subclasses.
+  #
+  # The inheritance model is what makes an Actor by itself useful. Actors can have one or more children, which can be
+  # any type of Actor. Those Actors can in turn have any number of child Actors, and so on, creating a sort of tree
+  # structure. A parent Actor's transform is inherited by its children, so moving or rotating a parent Actor moves or
+  # rotates all of its children relative to its parent. And when a parent is drawn, all of its children are drawn as well
+  # (see #draw for exceptions).
+  #
+  # One common application of this is to use a plain Actor as a root object to which all other elements visible in the
+  # game world are added. As the player moves through the game world, rather than move the position of each game
+  # element across the screen to simulate travel, you need only move the root Actor and all other Actors will be moved
+  # similarly. This root actor then acts like a "stage" or "camera". For this reason, one could think of a plain Actor as
+  # sort of a "container" for other Actors, a way to keep them all organized and related.
+  #
+  # The behavior of inheritance can modified by setting various properties. Read on for more details.
+  #
   class Actor
     attr_reader :transform, :parent, :children, :window
-    attr_accessor :is_visible, :is_tangible, :are_children_visible, :are_children_tangible, :is_mask, :color
 
+    ##
+    # If set to true, this Actor will be drawn to screen. If false, it will be skipped. The default is true.
+    #
+    attr_accessor :is_visible
+
+    ##
+    # If set to true, this Actor will respond to "point-in-shape" tests. If false, such tests will skip this Actor. The default
+    # is true.
+    #
+    attr_accessor :is_tangible
+
+    ##
+    # If set to true, all of this Actor's children will be drawn to screen. If false, they and their descendants will be
+    # skipped. The default is true.
+    #
+    attr_accessor :are_children_visible
+
+    ##
+    # If set to true, this Actor's children will respond to "point-in-shape" tests. If false, such tests will skip them and
+    # their descendants. The default is true.
+    #
+    attr_accessor :are_children_tangible
+
+    ##
+    # If set to true, this Actor will be treated as a "mask" for its parent regarding "point-in-shape" tests. If the point is
+    # in this Actor's bounds, it will act as though the point is in its parent's bounds instead of its own. The default is
+    # false.
+    #
+    attr_accessor :is_mask
+
+    ##
+    # The Gosu::Color to use when rendering this Actor.
+    #
+    attr_accessor :color
+
+    ##
+    # Creates a new Actor, setting all inheritance properties to their defaults and assigning a random color. Requires
+    # a Gosu::Window to be used when rendering.
+    #
     def initialize(window)
       @window = window
       @transform = Transform.new
@@ -24,17 +84,16 @@ module Gosling
       "#<#{self.class}:#{self.object_id}>"
     end
 
-    def parent=(parent)
-      return if parent == @parent
-      unless parent
-        raise Gosling::InheritanceError.new("You should use Actor.remove_child() instead of setting the parent directly.") if @parent.has_child?(self)
-      end
-      @parent = parent
-      if @parent
-        raise Gosling::InheritanceError.new("You should use Actor.add_child() instead of setting the parent directly.") unless @parent.has_child?(self)
-      end
-    end
-
+    ##
+    # Establishes a parent/child relationship between this actor and the one passed, respectively. The child Actor will
+    # appear relative to its parent, move as the parent moves, and draw when the parent draws.
+    #
+    # An Actor cannot be made a child of itself. Similarly, a child cannot be added to a parent if doing so would create
+    # a circular reference (e.g. a.add_child(b) followed by b.add_child(a)).
+    #
+    # If the child Actor already had a parent, the Actor is disassociated from its former parent before becoming
+    # associated with this one. An Actor can have only one parent at a time.
+    #
     def add_child(child)
       return if @children.include?(child)
       raise Gosling::InheritanceError.new("An Actor cannot be made a child of itself.") if child == self
@@ -49,6 +108,10 @@ module Gosling
       child.parent = self
     end
 
+    ##
+    # If the given Actor is a child of this Actor, it is disassociated from this Actor. In any case, the child Actor is
+    # immediately orphaned.
+    #
     def remove_child(child)
       return unless @children.include?(child)
 
@@ -56,94 +119,137 @@ module Gosling
       child.parent = nil
     end
 
+    ##
+    # Returns true if this Actor has the given Actor as a child.
+    #
     def has_child?(child)
       @children.include?(child)
     end
 
+    ##
+    # Wrapper method. Returns this Actor's x position in relative space. See Transform#translation.
+    #
     def x
-      @transform.translation[0]
+      @transform.translation.x
     end
 
+    ##
+    # Wrapper method. Sets this Actor's x position in relative space. See Transform#translation.
+    #
     def x=(val)
-      array = @transform.translation.to_a
-      array[0] = val
-      @transform.set_translation(Vector.elements(array))
+      @transform.translation = val, @transform.translation.y
     end
 
+    ##
+    # Wrapper method. Returns this Actor's y position in relative space. See Transform#translation.
+    #
     def y
-      @transform.translation[1]
+      @transform.translation.y
     end
 
+    ##
+    # Wrapper method. Sets this Actor's y position in relative space. See Transform#translation.
+    #
     def y=(val)
-      array = @transform.translation.to_a
-      array[1] = val
-      @transform.set_translation(Vector.elements(array))
+      @transform.translation = @transform.translation.x, val
     end
 
+    ##
+    # Wrapper method. Returns this Actor's position in relative space as a Snow::Vec3. See Transform#translation.
+    #
     def pos
-      Vector[x, y, 0]
+      @transform.translation
     end
 
+    ##
+    # Wrapper method. Sets this Actor's position in relative space. See Transform#translation.
+    #
     def pos=(val)
-      array = @transform.translation.to_a
-      array[0] = val[0]
-      array[1] = val[1]
-      @transform.set_translation(Vector.elements(array))
+      @transform.translation = val
     end
 
+    ##
+    # Wrapper method. Returns the x component of the centerpoint of this Actor. See Transform#center.
+    #
     def center_x
-      @transform.center[0]
+      @transform.center.x
     end
 
+    ##
+    # Wrapper method. Sets the x component of the centerpoint of this Actor. See Transform#center.
+    #
     def center_x=(val)
-      array = @transform.center.to_a
-      array[0] = val
-      @transform.set_center(Vector.elements(array))
+      @transform.center = val, @transform.center.y
     end
 
+    ##
+    # Wrapper method. Returns the y component of the centerpoint of this Actor. See Transform#center.
+    #
     def center_y
-      @transform.center[1]
+      @transform.center.y
     end
 
+    ##
+    # Wrapper method. Sets the y component of the centerpoint of this Actor. See Transform#center.
+    #
     def center_y=(val)
-      array = @transform.center.to_a
-      array[1] = val
-      @transform.set_center(Vector.elements(array))
+      @transform.center = @transform.center.x, val
     end
 
+    ##
+    # Wrapper method. Returns the x component of the scaling of this Actor. See Transform#scale.
+    #
     def scale_x
-      @transform.scale[0]
+      @transform.scale.x
     end
 
+    ##
+    # Wrapper method. Sets the x component of the scaling of this Actor. See Transform#scale.
+    #
     def scale_x=(val)
-      array = @transform.scale.to_a
-      array[0] = val
-      @transform.set_scale(Vector.elements(array))
+      @transform.scale = val, @transform.scale.y
     end
 
+    ##
+    # Wrapper method. Returns the y component of the scaling of this Actor. See Transform#scale.
+    #
     def scale_y
-      @transform.scale[1]
+      @transform.scale.y
     end
 
+    ##
+    # Wrapper method. Sets the y component of the scaling of this Actor. See Transform#scale.
+    #
     def scale_y=(val)
-      array = @transform.scale.to_a
-      array[1] = val
-      @transform.set_scale(Vector.elements(array))
+      @transform.scale = @transform.scale.x, val
     end
 
+    ##
+    # Wrapper method. Returns this Actor's rotation in radians. See Transform#rotation.
+    #
     def rotation
       @transform.rotation
     end
 
+    ##
+    # Wrapper method. Sets this Actor's rotation in radians. See Transform#rotation.
+    #
     def rotation=(val)
-      @transform.set_rotation(val)
-    end
-
-    def render(matrix)
-    end
-
+      @transform.rotation = val
+    end
+
+    ##
+    # Calls #render on this Actor, drawing it to the screen if #is_visible is set to true (the default).
+    #
+    # The Actor's transforms, if any, will be applied prior to rendering. If an optional Snow::Mat3 matrix transform is
+    # given, the Actor will be transformed by a combination of that matrix transform and its own.
+    #
+    # If the #are_children_visible flag is set to true (the default), then this method will recursively call draw on each
+    # of the Actor's children, passing them the combined matrix used to render the parent. Otherwise, children will
+    # be skipped and not drawn.
+    #
     def draw(matrix = nil)
-      matrix ||= Matrix.identity(3)
+      matrix ||= Snow::Mat3.new
       transform = matrix * @transform.to_matrix
       render(transform) if @is_visible
       if @are_children_visible
@@ -151,10 +257,28 @@ module Gosling
       end
     end
 
+    ##
+    # Returns false. Actors have no shape, and so no point is in their bounds. Subclasses override this method with
+    # shape-specific behavior.
+    #
     def is_point_in_bounds(point)
       false
     end
 
+    ##
+    # Given a point in global space, tests this Actor and each of its children, returning the first Actor for whom this
+    # point is inside its shape. Respects each Actor's transforms as well as any it may inherit from its ancestors.
+    # Useful for determining which Actor the user may have clicked on.
+    #
+    # If the #is_tangible flag is set to false, this Actor will not be tested. The default is true.
+    #
+    # If the #are_children_tangible flag is set to false, this Actor's children will not be tested. The default is true.
+    #
+    # If the #is_mask flag is set to true, a positive test from this Actor instead returns its parent Actor, if any. The
+    # default is false.
+    #
+    # If the point is not inside this Actor or any of its children (excluding any skipped Actors), nil is returned.
+    #
     def get_actor_at(point)
       hit = nil
       if @are_children_tangible
@@ -171,6 +295,9 @@ module Gosling
       hit
     end
 
+    ##
+    # Functions similarly to #get_actor_at, but returns a list of +all+ Actors for whom the point is inside their shape.
+    #
     def get_actors_at(point)
       actors = []
       if @are_children_tangible
@@ -186,50 +313,103 @@ module Gosling
       actors
     end
 
-    def get_global_transform
-      tf = if parent
-        parent.get_global_transform * @transform.to_matrix
+    ##
+    # Returns a Snow::Mat3 transformation matrix combining this Actor's transforms as well as all of its ancestors.
+    # This matrix can be used to transform a point in this Actor's local space to its global equivalent (the geometric
+    # space of its root ancestor).
+    #
+    def get_global_transform(out = nil)
+      if parent
+        out ||= Snow::Mat3.new
+        @transform.to_matrix.multiply(parent.get_global_transform, out)
+        out
       else
         @transform.to_matrix
       end
-      return tf
     end
 
+    ##
+    # Returns the global x/y position of this actor (where it is relative to its root ancestor). This value is calculated
+    # using the Actor's center (see Transform#center).
+    #
     def get_global_position
       tf = get_global_transform
-      Transform.transform_point(tf, Vector[@transform.center[0], @transform.center[1], 0])
+      Transform.transform_point(tf, @transform.center)
     end
 
+    ##
+    # Wrapper method. Returns this Actor's alpha value (0-255).
+    #
     def alpha
       @color.alpha
     end
 
+    ##
+    # Wrapper method. Sets this Actor's alpha value (0-255).
+    #
     def alpha=(val)
       @color.alpha = val
     end
 
+    ##
+    # Wrapper method. Returns this Actor's red value (0-255).
+    #
     def red
       @color.red
     end
 
+    ##
+    # Wrapper method. Sets this Actor's red value (0-255).
+    #
     def red=(val)
       @color.red = val
     end
 
+    ##
+    # Wrapper method. Returns this Actor's green value (0-255).
+    #
     def green
       @color.green
     end
 
+    ##
+    # Wrapper method. Sets this Actor's green value (0-255).
+    #
     def green=(val)
       @color.green = val
     end
 
+    ##
+    # Wrapper method. Returns this Actor's blue value (0-255).
+    #
     def blue
       @color.blue
     end
 
+    ##
+    # Wrapper method. Sets this Actor's blue value (0-255).
+    #
     def blue=(val)
       @color.blue = val
     end
+
+    protected
+
+    def render(matrix)
+    end
+
+    ##
+    # Internal use only. See #add_child and #remove_child.
+    #
+    def parent=(parent)
+      return if parent == @parent
+      unless parent
+        raise Gosling::InheritanceError.new("You should use Actor.remove_child() instead of setting the parent directly.") if @parent.has_child?(self)
+      end
+      @parent = parent
+      if @parent
+        raise Gosling::InheritanceError.new("You should use Actor.add_child() instead of setting the parent directly.") unless @parent.has_child?(self)
+      end
+    end
   end
-end
+end

data/lib/gosling/circle.rb

@@ -2,26 +2,52 @@ require_relative 'actor.rb'
 require_relative 'collision.rb'
 
 module Gosling
+  ##
+  # Represents an Actor with a circular shape, defined by a mutable radius. The circle is rendered relative to the
+  # Circle's center (see Transform#center).
+  #
   class Circle < Actor
+    ##
+    # How many vertices to use when rendering circles. More vertices means more accurate rendering at the cost of
+    # performance.
+    #
     RENDER_VERTEX_COUNT = 16
 
     attr_reader :radius
 
+    ##
+    # Creates a new Circle with initial radius of zero.
+    #
     def initialize(window)
       super(window)
       @radius = 0
     end
 
+    ##
+    # Sets this circle's radius. Radius must be a positive integer.
+    #
     def radius=(val)
       raise ArgumentError.new("Circle.radius cannot be negative") if val < 0
       @radius = val
     end
 
+    ##
+    # Returns the angle's corresponding unit vector times this circle's radius.
+    #
     def get_point_at_angle(radians)
       raise ArgumentError.new("Expected Numeric, but received #{radians.inspect}!") unless radians.is_a?(Numeric)
-      Vector[Math.cos(radians) * @radius, Math.sin(radians) * @radius, 0]
+      Snow::Vec3[Math.cos(radians) * @radius, Math.sin(radians) * @radius, 0]
     end
 
+    ##
+    # Returns true if the point is inside the Circle, false otherwise.
+    #
+    def is_point_in_bounds(point)
+      Collision.is_point_in_shape?(point, self)
+    end
+
+    private
+
     def render(matrix)
       local_vertices = (0...RENDER_VERTEX_COUNT).map do |i|
         get_point_at_angle(Math::PI * 2 * i / RENDER_VERTEX_COUNT)
@@ -40,9 +66,5 @@ module Gosling
         i += 1
       end
     end
-
-    def is_point_in_bounds(point)
-      Collision.is_point_in_shape?(point, self)
-    end
   end
 end