peregrine 0.1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Kevin Owen <solucet@icloud.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,36 @@
+# Peregrine
+1. _adjective: foreign; alien; wandering, traveling, or migrating._
+2. _noun: a kick-ass falcon._
+
+## Summary
+Peregrine is a highly adaptive, extensible Entity-Component framework written for the Ruby programming language. Peregrine is platform and dependency agnostic, requiring _no_ additional dependencies for use as a library -- and works just as well with JRuby or Rubinius as it does with MRI Ruby.
+
+## Installation
+Peregrine is available as a library in the usual way -- just use RubyGems.
+
+```sh
+$ gem install peregrine
+```
+
+Want to help with development (or hack at the source)? Just clone [the GitHub repository][peregrine],  use Bundler, and you're good to go.
+
+```sh
+$ git clone git@github.com:solucet/peregrine.git
+$ gem install bundler
+$ cd peregrine/ && bundle
+```
+
+## Documentation
+The framework has been heavily documented with information and should serve you well. If you installed Peregrine from the GitHub repository and installed the development dependencies, you can generate a local copy of its RDoc documentation by running `rake rdoc`.
+
+If you are unfamiliar with Entity-Component design, it is highly recommended that you read about it in addition to reading the documentation for the Peregrine framework. Chris Powell wrote a [great series of tutorials][recf-tutorial] on using EC design in JRuby on his blog which also includes links to further reading on the subject.
+
+## Thanks
+Special thanks go to Chris Powell, as the Peregrine framework was conceptually inspired by his [Ruby Entity-Component Framework][recf] and its related tutorials (which are definitely recommended reading).
+
+## License
+Peregrine is made available under the terms of the MIT License. See the included LICENSE file for more information.
+
+[peregrine]:     https://github.com/solucet/peregrine
+[recf]:          https://github.com/cpowell/ruby-entity-component-framework
+[recf-tutorial]: http://cbpowell.wordpress.com/2012/10/30/

data/lib/peregrine/collections/common.rb

@@ -0,0 +1,12 @@
+require 'peregrine/collections/named'
+require 'peregrine/collections/tagged'
+
+module Peregrine
+  module Collections
+    # Includes instance method definitions available in the Collections::Named
+    # and Collections::Tagged modules.
+    module Common
+      include Named, Tagged
+    end
+  end
+end

data/lib/peregrine/collections/composite.rb

@@ -0,0 +1,33 @@
+module Peregrine
+  module Collections
+    # Provides methods for filtering Entity objects contained in a collection.
+    # This module is intended to be an extension to existing collection
+    # instances.
+    module Composite
+      # Returns an array of all Entities in the collection which include all of
+      # the given Component classes. Yields the matching Entity instances if a
+      # block is given.
+      def with_components(*list)
+        entities = select do |item|
+          next unless item.respond_to?(:component_classes)
+          list.all? { |component| item.component_classes.include?(component) }
+        end
+        entities.each { |entity| yield entity } if block_given?
+        entities.extend(Collections)
+      end
+      alias :with_component :with_components
+      
+      # Returns an array of all Entities in the collection which include _any_
+      # of the given Component classes. Yields the matching Entity instances if
+      # a block is given.
+      def with_any_component(*list)
+        entities = select do |item|
+          next unless item.respond_to?(:component_classes)
+          !(item.component_classes & list).empty?
+        end
+        entities.each { |entity| yield entity } if block_given?
+        entities.extend(Collections)
+      end
+    end
+  end
+end

data/lib/peregrine/collections/named.rb

@@ -0,0 +1,34 @@
+module Peregrine
+  module Collections
+    # Provides methods for filtering collections by item names. This module is
+    # intended to be an extension to existing collection instances.
+    module Named
+      # Returns an array of all items with a name that matches the given
+      # matcher. The matcher may be a Regexp for fine-tuned matching or any
+      # other object for specific equality matching. Yields the matching items
+      # in the collection if a block is given.
+      # 
+      # ==== Examples
+      # 
+      # Using a regular expression as a matcher:
+      #     manager = Peregrine::EntityManager.new do |manager|
+      #       manager.spawn { |entity| entity.name = 'Example' }
+      #     end
+      #     manager.entities.named(/^Ex/) # => [ Entity 'Example' ... ]
+      # 
+      # Using a string as a matcher:
+      #     manager = Peregrine::EntityManager.new do |manager|
+      #       manager.spawn { |entity| entity.name = 'Example' }
+      #     end
+      #     manager.entities.named('Example') # => [ Entity 'Example' ... ]
+      def named(matcher)
+        items = select do |item|
+          next unless item.respond_to?(:name)
+          matcher.is_a?(Regexp) ? item.name[matcher] : item.name == matcher.to_s
+        end
+        items.each { |item| yield item } if block_given?
+        items.extend(Collections)
+      end
+    end
+  end
+end

data/lib/peregrine/collections/systemic.rb

@@ -0,0 +1,30 @@
+module Peregrine
+  module Collections
+    # Provides methods for filtering System objects contained in a collection.
+    # This module is intended to be an extension to existing collection
+    # instances.
+    module Systemic
+      # Returns an array of enabled System objects in the collection. Yields the
+      # matching System instances if a block is given.
+      def enabled
+        systems = select do |system|
+          next unless system.respond_to?(:enabled?)
+          system.enabled?
+        end
+        systems.each { |system| yield system } if block_given?
+        systems.extend(Collections)
+      end
+      
+      # Returns an array of disabled System objects in the collection. Yields
+      # the matching System instances if a block is given.
+      def disabled
+        systems = select do |system|
+          next unless system.respond_to?(:enabled?)
+          !system.enabled?
+        end
+        systems.each { |system| yield system } if block_given?
+        systems.extend(Collections)
+      end
+    end
+  end
+end

data/lib/peregrine/collections/tagged.rb

@@ -0,0 +1,38 @@
+module Peregrine
+  module Collections
+    # Provides methods for filtering collections by item tags. This module is
+    # intended to be an extension to existing collection instances.
+    module Tagged
+      # Returns an array of objects within this collection with all of the given
+      # tags. Yields the tagged items in the collection if a block is given.
+      def tagged(*list)
+        items = select do |item|
+          next unless item.respond_to?(:tags)
+          list.all? { |tag| item.tags.include?(tag) }
+        end
+        items.each { |item| yield item } if block_given?
+        items.extend(Collections)
+      end
+      
+      # Returns an array of objects within this collection that contain any of
+      # the given tags. Yields the tagged items in the collection if a block is
+      # given.
+      def any_tagged(*list)
+        items = select do |item|
+          next unless item.respond_to?(:tags)
+          !(item.tags & list).empty?
+        end
+        items.each { |item| yield item } if block_given?
+        items.extend(Collections)
+      end
+      
+      # Returns an array of objects in this collection which are not tagged.
+      # Yields the untagged items in the collection if a block is given.
+      def untagged
+        items = select { |i| i.respond_to?(:tags) ? i.tags.empty? : true }
+        items.each { |item| yield item } if block_given?
+        items.extend(Collections)
+      end
+    end
+  end
+end

data/lib/peregrine/collections.rb

@@ -0,0 +1,25 @@
+# Require all Ruby files in the 'collections/' directory. Using +File.join+ to
+# ensure that all files are properly required regardless of the directory
+# separator in use.
+Dir[File.join(File.dirname(__FILE__), 'collections', '*.rb')].each do |file|
+  require file
+end
+
+module Peregrine
+  # This module provides modules which define instance methods to be used by
+  # collections (such as arrays or hashes) with methods for filtering thier
+  # collected items. These modules are designed to be extensions to instances of
+  # collections so as not to pollute the default Ruby collections.
+  # 
+  # Note that arrays returned from any of these modules are already extended
+  # with all of the defined collection modules, facilitating chaining of
+  # collection filtering methods.
+  module Collections
+    # Extends all of the constants defined within this module to the parent
+    # which is extended by this module -- essentially a shortcut to extend with
+    # all of the defined collections.
+    def self.extended(parent)
+      parent.send(:extend, *constants.map { |const| const_get(const) })
+    end
+  end
+end

data/lib/peregrine/component.rb

@@ -0,0 +1,59 @@
+require 'peregrine/features'
+
+module Peregrine
+  # == Summary
+  # 
+  # Components serve as data storage for Entity objects. Component objects, by
+  # definition, should _not_ contain any logic -- they serve only as a way to
+  # store information or as a "flag" for an Entity to be used by a System to
+  # implement the actual logic.
+  # 
+  # == Usage
+  # 
+  # It is expected that developers will subclass the Component class in order
+  # to create their own individual Components. When subclassing the Component,
+  # it is important to note that you should _not_ overwrite the +#initialize+
+  # method, and instead overwite the +#initialize_data+ method in order to
+  # instantiate a Component. Any additional arguments given to +Component.new+
+  # are passed along to the +#initialize_data+ method.
+  # 
+  # == Example
+  # 
+  #    class Mortal < Peregrine::Component
+  #      attr_reader :health
+  #      
+  #      # Initializing the data for this Component object.
+  #      def initialize_data(health = 100, max_health = 100)
+  #        @health  = health
+  #        @maximum = max_health
+  #      end
+  #      
+  #      # Do not implement logic, but define limits for data storage.
+  #      def health=(value)
+  #        @health = [0, value, @maximum].sort[1]
+  #      end
+  #    end
+  class Component
+    include Features
+    
+    # Create a new Component instance. Any arguments given to this method are 
+    # passed to the +initialize_data+ method. Yields the newly instanced
+    # Component if a block is given.
+    def initialize(*data_args)
+      initialize_data(*data_args)
+      yield self if block_given?
+    end
+    
+    # Intended to be overwritten by subclasses of the Component to initialize
+    # the data used. Additional arguments passed to +Component.new+ are passed
+    # to this method directly. This method does nothing on its own.
+    def initialize_data
+    end
+    
+    # Presents a human-readable summary of the Component.
+    def to_s
+      "Component '#{name}' #{id}"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/peregrine/entity.rb

@@ -0,0 +1,130 @@
+require 'peregrine/collections/common'
+require 'peregrine/features'
+require 'securerandom'
+
+module Peregrine
+  # == Summary
+  # 
+  # An Entity is any object within your project -- literally almost anything.
+  # Entities are designed to hold Component objects which determine what the
+  # Entity contains in terms of data. Components are also regularly used to
+  # "flag" an Entity -- for example, adding an empty Component +Renderable+
+  # would flag to System objects that this Entity can be rendered.
+  # 
+  # Essentially, Entity objects are little more than an identifier which serves
+  # as storage for Component objects. They do nothing more than store
+  # Components and provide methods for adding, removing, and filtering the
+  # contained Components.
+  # 
+  # == Usage
+  # 
+  # In general, it's best not to use Entity objects directly, but to make use
+  # of EntityManager objects which serve to organize and manage collections of
+  # Entity instances. See the EntityManager class' documentation for more
+  # information on how to use them.
+  class Entity
+    include Features
+    
+    # Array of Component objects attached to this Entity.
+    attr_reader :components
+    
+    # Symbol representing the UUID of this Entity.
+    attr_reader :uuid
+    
+    # Creates a new Entity instance and adds the given Component constants or
+    # instances to the Entity. Yields the newly created Entity if a block is
+    # given.
+    # 
+    # ==== Example
+    # 
+    #    Peregrine::Entity.new(Peregrine::Component) do |instance|
+    #      # Entity names are optional, but let's name this one.
+    #      instance.name = 'Example'
+    #    end # => Entity 'Example' 0xdf7258 (1)
+    def initialize(*components)
+      @components = [].extend(Collections::Common)
+      @uuid       = SecureRandom.uuid.to_sym
+      add_components(*components)
+      yield self if block_given?
+    end
+    
+    # Adds the given Component constants or instances to this Entity. Constants
+    # given are automatically instanced. Ignores Component classes which are 
+    # already present in the Entity. Returns the array of Component objects
+    # attached to this Entity after all additions.
+    # 
+    # ==== Example
+    # 
+    #    class Example < Peregrine::Component ; end
+    #    
+    #    entity = Peregrine::Entity.new
+    #    entity.add_components(Example) # => [Component 'Example' ...]
+    def add_components(*components)
+      components.each do |component|
+        component = component.new if component.class == Class
+        unless component_classes.include?(component.class)
+          @components.push(component)
+        end
+      end
+      @components
+    end
+    alias :add_component :add_components
+    
+    # Removes Component objects of the given classes from the Entity. Returns an
+    # array of the removed Component objects.
+    def remove_components!(*components)
+      removed = []
+      components.each do |flag|
+        @components.reject! { |c| c.class == flag ? removed.push(c) : false }
+      end
+      removed.extend(Collections::Common)
+    end
+    alias :remove_component! :remove_components!
+    
+    # Returns an array of all Component classes attached to this Entity. Yields
+    # the Component classes if a block is given.
+    def component_classes
+      components = @components.map { |component| component.class }.uniq
+      components.each { |component| yield component } if block_given?
+      components.extend(Collections::Common)
+    end
+    
+    # Returns all of the Component objects attached to this Entity of the exact
+    # given class. Yields the Component objects if a block is given.
+    # 
+    # ==== Example
+    # 
+    #    class Example < Peregrine::Component ; end
+    #    
+    #    entity = Peregrine::Entity.new(Example)
+    #    entity.components_of_class(Example) # => [Component 'Example' ...]
+    def components_of_class(const)
+      components = @components.select { |c| c.class == const }
+      components.each { |component| yield component } if block_given?
+      components.extend(Collections::Common)
+    end
+    
+    # Returns all of the Component objects attached to this Entity descended
+    # from the given class or module. Yields the Component objects if a block is
+    # given.
+    # 
+    # ==== Example
+    # 
+    #    class Example < Peregrine::Component ; end
+    #    
+    #    entity = Peregrine::Entity.new(Peregrine::Component, Example)
+    #    entity.components_of_kind(Peregrine::Component)
+    #      # => [Component 'Peregrine::Component' ..., Component 'Example' ...]
+    def components_of_kind(const)
+      components = @components.select { |c| c.class.ancestors.include?(const) }
+      components.each { |component| yield component } if block_given?
+      components.extend(Collections::Common)
+    end
+    
+    # Presents a human-readable summary of the Entity.
+    def to_s
+      "Entity '#{name}' #{uuid} (#{@components.size})"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/peregrine/entity_manager.rb

@@ -0,0 +1,164 @@
+require 'peregrine/collections'
+require 'peregrine/entity'
+require 'peregrine/features'
+
+module Peregrine
+  # == Summary
+  # 
+  # The EntityManager is an object designed to create, organize, and filter an
+  # array of Entity objects and manage System objects which implement logic for
+  # those Entities. Essentially, the EntityManager serves to group related
+  # Entity objects and provide them with the Systems that act upon them.
+  # 
+  # == Usage
+  # 
+  # The EntityManager is designed to group related Entity objects with the
+  # System instances which provide their logic. As such, it is recommended that
+  # you utilize as many instances of EntityManager objects as your application
+  # requires.
+  # 
+  # EntityManager objects automatically extend their arrays of Entity and System
+  # objects with instance methods designed to facilitate filtering of the
+  # managed items each respectively contain. Entities may be filtered by name,
+  # included (or excluded) tags, and which Component classes they may or may not
+  # contain. Likewise, System objects may be filtered based on any tags they do
+  # or do not have as well as by name.  For more detailed information about the
+  # available filtering methods, please see the documentation for the
+  # Peregrine::Collections module and the modules that it contains.
+  # 
+  # Note that Peregrine itself does not include any objects for grouping
+  # EntityManager instances together (unlike some other frameworks) -- this
+  # functionality is left up to individual developers and their preferred
+  # methods. Use your EntityManagers in whatever way you personally feel would
+  # best benefit _you_ and _your_ application.
+  # 
+  # == Examples
+  # 
+  # Naming EntityManager instances, spawning Entity objects, and filtering
+  # Entity objects based on tags:
+  # 
+  #    class Example < Peregrine::Component ; end
+  #    
+  #    manager = Peregrine::EntityManager.new { |m| m.name = 'Example' }
+  #    5.times do |iterator|
+  #      iterator += 1
+  #      manager.spawn(Example) do |entity|
+  #        entity.name = iterator
+  #        iterator.even? ? entity.add_tag(:even) : entity.add_tag(:odd)
+  #      end
+  #    end
+  #    manager.entities.tagged(:even) # => [Entity '2' ..., Entity '4' ...]
+  # 
+  # Finding all basic entities and adding a component to them with a block:
+  # 
+  #    manager = Peregrine::EntityManager.new
+  #    rand(1..20).times { manager.spawn }
+  #    manager.basic_entities do |entity|
+  #      e.add_component(Peregrine::Component)
+  #    end
+  class EntityManager
+    include Features
+    
+    # Array of entities owned by this EntityManager.
+    attr_reader :entities
+    
+    # Array of Systems operating within this EntityManager.
+    attr_reader :systems
+    
+    # Creates a new EntityManager instance. Yields the newly created instance if
+    # a block is given.
+    def initialize
+      @entities = [].extend(Collections::Common, Collections::Composite)
+      @systems  = [].extend(Collections::Common, Collections::Systemic)
+      yield self if block_given?
+    end
+    
+    # Calls +process+ on each enabled System within this EntityManager. The
+    # +process+ method is _intended_ to be called once per tick, but the actual
+    # implementation is left up to the developer. Returns the array of System
+    # objects operating within the EntityManager.
+    def process
+      @systems.each { |system| system.process if system.enabled? }
+    end
+    
+    # Spawns a new Entity with the given Components and pushes the new Entity
+    # into the array of owned entities. Returns the spawned Entity. Yields the
+    # new Entity before pushing it into the owned entities array if a block is
+    # given.
+    def spawn(*arguments)
+      entity = Peregrine::Entity.new(*arguments)
+      yield entity if block_given?
+      @entities.push(entity)
+      entity
+    end
+    
+    # Adds the given Entity instances (or instantiated Entity constants) to the
+    # EntityManager. Returns the array of managed Entity objects.
+    def add_entities(*entities)
+      entities.each do |entity|
+        entity = entity.new if entity.class == Class
+        @entities.push(entity)
+      end
+      @entities
+    end
+    alias :add_entity :add_entities
+    
+    # Removes the given Entity instances from the EntityManager. Returns the
+    # removed Entity objects. Intended to be used with the EntityManager's
+    # filtering methods to select appropriate Entity instances.
+    def remove_entities!(*entities)
+      removed = []
+      @entities.reject! do |entity|
+        entities.include?(entity) ? removed.push(entity) : false
+      end
+      removed.extend(Collections::Common, Collections::Composite)
+    end
+    alias :remove_entity! :remove_entities!
+    
+    # Returns an array of all managed Entity objects without Components. Yields
+    # the array of basic Entities if a block is given. Note that "basic" Entity
+    # objects _may_ still be named or tagged.
+    def basic_entities
+      entities = @entities.select { |e| e.components.empty? }
+      entities.each { |entity| yield entity } if block_given?
+      entities.extend(Collections::Common, Collections::Composite)
+    end
+    
+    # Adds the given System instances (or instantiated System constants) to the
+    # EntityManager, updating the System's manager. Returns the array of System
+    # objects operating in the EntityManager.
+    def add_systems(*systems)
+      systems.each do |system|
+        if system.class == Class
+          system = system.new(self)
+        else
+          @systems.push(system)
+          system.manager = self
+        end
+      end
+      @systems
+    end
+    alias :add_system :add_systems
+    
+    # Removes the given System instances (or all System classes of the given
+    # constants) from the EntityManager, updating the manager of each System.
+    # Returns an array of the removed System instances.
+    def remove_systems!(*systems)
+      removed = []
+      @systems.reject! do |system|
+        if systems.include?(system) || systems.include?(system.class)
+          system.manager = nil
+          removed.push(system)
+        else false end
+      end
+      removed.extend(Collections::Common, Collections::Systemic)
+    end
+    
+    # Presents a human-readable summary of the EntityManager.
+    def to_s
+      "Entity Manager '#{name}' #{id} " <<
+      "(#{@entities.size} Entities, #{@systems.size} Systems)"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/peregrine/features/configurable.rb

@@ -0,0 +1,20 @@
+module Peregrine
+  module Features
+    # Provides the +configure+ method. Intended to be included in classes
+    # requiring this functionality.
+    module Configurable
+      # Yields the object this method is called on. This method is intended to
+      # allow configuration of Peregrine objects with other features. Returns
+      # the object this method was called on.
+      # 
+      # ==== Example
+      # 
+      #    entity = Peregrine::Entity.new
+      #    entity.configure { |e| e.name = 'Example' } # => Entity 'Example' ...
+      def configure
+        yield self if block_given?
+        self
+      end
+    end
+  end
+end

data/lib/peregrine/features/identifiable.rb

@@ -0,0 +1,12 @@
+module Peregrine
+  module Features
+    # Provides the +id+ method to extract an object's +object_id+ as a hex
+    # string. Intended to be included in classes requiring this functionality.
+    module Identifiable
+      # Returns the object's +object_id+ as a hexadecimal string.
+      def id
+        '0x' << (object_id << 1).to_s(16)
+      end
+    end
+  end
+end

data/lib/peregrine/features/nameable.rb

@@ -0,0 +1,17 @@
+module Peregrine
+  module Features
+    # Provides methods for naming objects. Intended to be included in classes
+    # requiring this functionality.
+    module Nameable
+      # Returns the name of the object. Lazily evaluated.
+      def name
+        @name ||= self.class.to_s
+      end
+      
+      # Sets the name of the object to the given value after String coercion.
+      def name=(value)
+        @name = value.to_s
+      end
+    end
+  end
+end

data/lib/peregrine/features/taggable.rb

@@ -0,0 +1,32 @@
+module Peregrine
+  module Features
+    # Provides methods for adding and removing tags to and from objects. This
+    # essentially provides yet another method for identifying and filtering
+    # various objects. Intended to be included in classes requiring this
+    # functionality.
+    module Taggable
+      # Returns the array of tags this object contains. Lazily evaluated.
+      def tags
+        @tags ||= []
+      end
+      
+      # Add the given tags to the object. Tags may be any kind of object. Tags
+      # identical to existing tags are ignored. Returns an array of all tags
+      # this object contains.
+      def add_tags(*list)
+        tags.push(*list).uniq!
+        tags
+      end
+      alias :add_tag :add_tags
+      
+      # Removes the given tags from the object. Returns an array of the removed
+      # tags.
+      def remove_tags!(*list)
+        removed = []
+        tags.reject! { |tag| list.include?(tag) ? removed.push(tag) : false }
+        removed
+      end
+      alias :remove_tag! :remove_tags!
+    end
+  end
+end

data/lib/peregrine/features.rb

@@ -0,0 +1,20 @@
+# Require all Ruby files in the 'features/' directory. Using +File.join+ to
+# ensure that all files are properly required regardless of the directory
+# separator in use.
+Dir[File.join(File.dirname(__FILE__), 'features', '*.rb')].each do |file|
+  require file
+end
+
+module Peregrine
+  # This module provides modules which add instance methods to Peregrine objects
+  # that provide functionality such as tags, names, and identifiers. These
+  # modules are designed to be included in Peregrine classes.
+  module Features
+    # Includes all of the constants defined within this module to the parent
+    # which includes this module -- essentially a shortcut to include all of the
+    # defined features.
+    def self.included(parent)
+      parent.send(:include, *constants.map { |const| const_get(const) })
+    end
+  end
+end

data/lib/peregrine/system.rb

@@ -0,0 +1,129 @@
+require 'peregrine/collections'
+require 'peregrine/features'
+
+module Peregrine
+  # == Summary
+  # 
+  # The System class implements logic for a collection of Entity objects and
+  # resides within an EntityManager instance. The System class present in the
+  # Peregrine framework serves as a basis for creating subclasses to implement
+  # logic and perform no such logic themselves (in fact, they raise a
+  # +NotImplementedError+ when processed).
+  # 
+  # == Usage
+  # 
+  # The default System class is very minimal and performs no actual logic on its
+  # own. Individual developers are intended to subclass the System and implement
+  # the needed logic in their own +process+ methods.
+  # 
+  # In addition to this, System classes may be enabled or disabled. Disabled
+  # System classes may still be explicitly updated by calling their +process+
+  # method, but will not automatically fire when the EntityManager that they
+  # belong to calls its +process+ method. Systems are enabled by default, but
+  # may be disabled when instanced by passing a block or calling the +configure+
+  # method with a block.
+  # 
+  # Most System classes are expected to operate on a limited subset of the
+  # available Entity objects within the EntityManager that contains the System.
+  # As such, the +selector+ method has been provided to allow filtering the
+  # EntityManager's managed Entity objects. The +selector+ method returns a
+  # Proc object which is used by the +select+ method on the +entities+ array
+  # owned by the EntityManager. When overwritten, the +selector+ method ensures
+  # that the +entities+ method of the System only returns Entity objects that
+  # pass through the +selector+ method's block.
+  # 
+  # Given the implementation of the +selector+, it is _highly_ recommended that
+  # you wrap your Systems' +process+ methods in the +entities+ method to make
+  # sure that they only implement logic for the properly selected Entities.
+  # 
+  # == Example
+  # 
+  # To demonstrate how to write a System subclass, we'll build a simple System
+  # that simply acts on Entity objects that contain Components and removes the
+  # Components when processed.
+  # 
+  #    class Remover < Peregrine::System
+  #      def selector
+  #        ->(entity) { !entity.components.empty? }
+  #      end
+  #      
+  #      def process
+  #        entities.each do |entity|
+  #          entity.remove_components!(*entity.component_classes)
+  #        end
+  #      end
+  #    end
+  # 
+  # Now we'll create a new, disabled instance of the Remover System.
+  # 
+  #    manager = Peregrine::EntityManager.new
+  #    manager.add_system(Remover.new { |system| system.disable })
+  class System
+    include Features
+    
+    # The EntityManager object using this System instance.
+    attr_accessor :manager
+    
+    # Creates a new System instance operating within the given EntityManager
+    # and automatically adds the System to the EntityManager. Yields the newly
+    # created System if a block is given.
+    # 
+    # ==== Example
+    # 
+    #    manager = Peregrine::EntityManager.new { |m| m.name = 'Example' }
+    #    Peregrine::System.new(manager) do |system|
+    #      system.name = 'Example'
+    #      # Systems are enabled by default, but we want this one disabled.
+    #      system.disable
+    #    end # => - System 'Example' 0x1724d80 <Entity Manager 'Example' ...>
+    def initialize(manager = nil)
+      @enabled = true
+      @manager = manager
+      @manager.systems.push(self) if @manager.respond_to?(:systems)
+      yield self if block_given?
+    end
+    
+    # Provides the block to be given to the +entities+ method's +select+ call
+    # used to filter the Entity objects affected by the System. The default
+    # +selector+ implementation returns all Entity objects that are not +false+
+    # or +nil+. Intended to be overwritten in subclasses.
+    def selector
+      Proc.new { |entity| entity }
+    end
+    
+    # Returns an array of all of the Entity objects that this System should act
+    # upon. This method is intended to be used in the body of a subclass'
+    # +update+ method in order to facilitate only operating on the desired
+    # Entity objects. Entity objects are collected by calling +select+ on the
+    # EntityManager's +entities+ array with a block supplied by the System's
+    # +selector+ method. Yields each selected Entity object if a block is given.
+    def entities
+      return [] unless @manager.respond_to?(:entities)
+      @manager.entities.select(&selector).each do |entity|
+        yield entity if block_given?
+      end
+    end
+    
+    # Explicitly enables the System.
+    def enable() @enabled = true end
+    
+    # Explicitly disables the System.
+    def disable() @enabled = false end
+    
+    # Explicitly returns +true+ if the System is enabled, +false+ otherwise.
+    def enabled?() @enabled ? true : false end
+    
+    # Called whenever the EntityManager with this System is updated. This method
+    # is intended to be overwritten in subclasses by developers in order to
+    # implement logic. Only called by the EntityManager if the System is
+    # enabled.  Raises a +NotImplementedError+ by default.
+    def process() raise NotImplementedError end
+    
+    # Presents a human-readable summary of the System.
+    def to_s
+      status = enabled? ? '+' : '-'
+      "#{status} System '#{name}' #{id} <#{manager.name} #{manager.id}>"
+    end
+    alias :inspect :to_s
+  end
+end

data/lib/peregrine/version.rb

@@ -0,0 +1,4 @@
+module Peregrine
+  # Semantic version of the Peregrine framework.
+  VERSION = '0.1.0'
+end

data/lib/peregrine.rb

@@ -0,0 +1,6 @@
+# Require all Ruby files in the 'peregrine/' directory. Using +File.join+ to
+# ensure that all files are properly required regardless of the directory
+# separator in use.
+Dir[File.join(File.dirname(__FILE__), 'peregrine', '*.rb')].each do |file|
+  require file
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: peregrine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Kevin Owen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Peregrine is a minimal, highly adaptive Entity-Component design framework
+  for the Ruby scripting language designed for general-purpose programming.
+email:
+- solucet@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/peregrine/collections/common.rb
+- lib/peregrine/collections/composite.rb
+- lib/peregrine/collections/named.rb
+- lib/peregrine/collections/systemic.rb
+- lib/peregrine/collections/tagged.rb
+- lib/peregrine/collections.rb
+- lib/peregrine/component.rb
+- lib/peregrine/entity.rb
+- lib/peregrine/entity_manager.rb
+- lib/peregrine/features/configurable.rb
+- lib/peregrine/features/identifiable.rb
+- lib/peregrine/features/nameable.rb
+- lib/peregrine/features/taggable.rb
+- lib/peregrine/features.rb
+- lib/peregrine/system.rb
+- lib/peregrine/version.rb
+- lib/peregrine.rb
+- LICENSE
+- README.md
+homepage: https://github.com/solucet/peregrine
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Flexible Entity-Component framework for Ruby.
+test_files: []