darkholme 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c96502aea889b8b96233989a44c91611918115f4
-  data.tar.gz: 4bd198e683c64ad3b28a05536aa07034bbdb91eb
+  metadata.gz: e7887db34f894712a0b13a7b0efc0371af0983a4
+  data.tar.gz: 44a523114c61788c2c11d450df41e90179f3867d
 SHA512:
-  metadata.gz: 490d144381019b4ca83651917fdc71d74410fe2238c252079eb42e3b673b6f8e2a7eeea3eb58b371c540ac522b03f6b648beb5b411c4b25f8416f13daca6b9f6
-  data.tar.gz: e232f4dbde1ac5588e6e0e6ab9e8a3a8ec5d2fd9d34ac9db3eb5bf519a17c2c282df2ebee6ade2dec8dbd9fc5b85fd200fbd763bd00535e628235d67d181dc59
+  metadata.gz: ecdfaa52cc78ef4e681a84b4dc8a734a9a61c239171e75931fa7a5b756fa1a30626de6dc7274c94faba5215ad6836952ab2f9e87d05685ac01858b283b12ac3d
+  data.tar.gz: 4e83e7a54bdf7eeec2c35cc8d4c28d35087a26c6124899b509351c8db1bdb404f62a93954c11ea6537ec151b1fe977b16b163d8289525ab34fc45b7cc023b68e

data/README.md

@@ -2,14 +2,86 @@
 
 [![Build Status](https://travis-ci.org/massivedanger/darkholme.png?branch=master)](https://travis-ci.org/massivedanger/darkholme)
 
-> Who am I? That, my dear, is an excellent question. Though not one easily answered. 
+> Who am I? That, my dear, is an excellent question. Though not one easily answered.
 
-Darkholme is an [entity-component system](http://en.wikipedia.org/wiki/Entity_component_system) 
+Darkholme is an [entity-component system](http://en.wikipedia.org/wiki/Entity_component_system)
 written in Ruby. It's still early days for it, but I think it's ready for most basic use cases.
 
 ## Usage
 
-_COMING SOON!_
+First, you need to create an **Engine** to hold all the other parts of Darkholme.
+
+```ruby
+@engine = Darkholme::Engine.new
+```
+
+All of your **Systems** and **Entities** will be added to your engine, which will update
+them once per frame. Make sure you put an Engine#update inside of your game's update loop, like
+so:
+
+```ruby
+def update(delta)
+  @engine.update(delta)
+end
+```
+
+Now, you can define an Entity and add **Components** to it, which hold data for your systems
+to use. In this case, let's assume you've made a component called `Spatial` that holds an entity's
+position along with its velocity. Something like this:
+
+```ruby
+class Spatial < Darkholme::Component
+  attr_accessor :position, :velocity
+
+  def initialize
+    @position = { x: 0, y: 0 }
+    @velocity = { x: 0, y: 0 }
+  end
+end
+```
+
+And adding it:
+
+```ruby
+new_entity = Darkhole::Entity.new
+new_entity.add_component Spatial.new
+```
+
+Next is adding your entity to the engine and adding a new system that'll use the Spatial
+component and move the entity according to its velocity.
+
+Here's what the system could look like:
+
+```ruby
+class PositionSystem < Darkholme::System
+  has_family Spatial
+
+  def update(delta)
+    entities.each do |entity|
+      spatial = entity.component_for Spatial
+
+      spatial.position.x += spatial.velocity.x * delta
+      spatial.position.y += spatial.velocity.y * delta
+    end
+  end
+end
+```
+
+And adding it and the entity from before:
+
+```ruby
+engine.add_system PositionSystem.new
+engine.add_entity new_entity
+```
+
+Now, as another system modifies the entity's Spatial component velocity, the
+PositionSystem will position it according to its velocity, but properly using
+the delta between frames for smooth movement.
+
+It's highly encouraged to [read through the documentation](http://rdoc.info/github/massivedanger/darkholme/master/frames)
+for the gem, as it can answer most questions you might have about each individual method. Please
+[file an issue](https://github.com/massivedanger/darkholme/issues) if you think our documentation is
+lacking in some way. Thanks!
 
 ## Key concepts
 
@@ -40,7 +112,7 @@ means that systems won't loop through every single entity on update. They only l
 relevant entities. This is _awesome_. Maybe.
 
 ## Contributing to darkholme
- 
+
 - Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 - Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 - Fork the project.

data/VERSION

@@ -1 +1 @@
-0.9.1
+1.0.0

data/darkholme.gemspec

@@ -2,15 +2,15 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: darkholme 0.9.1 ruby lib
+# stub: darkholme 1.0.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "darkholme"
-  s.version = "0.9.1"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Massive Danger"]
-  s.date = "2014-02-23"
+  s.date = "2014-02-25"
   s.description = "An entity-component system in Ruby"
   s.email = "evan@massivedanger.com"
   s.extra_rdoc_files = [

data/lib/darkholme.rb

@@ -6,6 +6,6 @@ require 'darkholme/iterating_system'
 require 'darkholme/component'
 require 'darkholme/family'
 
+# Darkholme is an Entity-Component System by Massive Danger
 module Darkholme
-   
 end

data/lib/darkholme/bitset.rb

@@ -1,7 +1,17 @@
 module Darkholme
+  # A class for easier bitset management with handy bitwise methods
   class Bitset
-    attr_reader :bits, :set_indexes
-
+    attr_reader :bits
+    attr_reader :set_indexes
+
+    # Create a new Bitset with optional initial bits
+    #
+    # @param initial_bits [Array<Fixnum>] The initial bit indexes to set
+    #
+    # @example Setting multiple bits initially
+    #   Bitset.new 1, 2, 10, 30
+    #
+    # @return [Bitset] The new bitset
     def initialize(*initial_bits)
       @bits = initial_bits.map {|bit| convert_bit(bit) }.inject(:+) || 0
 
@@ -9,6 +19,13 @@ module Darkholme
       @set_indexes += initial_bits.uniq if initial_bits
     end
 
+    # Set the bit at an index to true or false.
+    # Sets the bit to 1, by default
+    #
+    # @param bit [Fixnum] Index of bitset to set
+    # @param value [Boolean] Whether to set the bit to 0 or 1
+    #
+    # @return [Fixnum] The bitset's integer representation after being modified
     def set(bit, value = true)
       if value
         @bits = union convert_bit(bit)
@@ -21,67 +38,117 @@ module Darkholme
       @bits
     end
 
+    # Set a bit at supplied index to 0
+    #
+    # @param bit [Fixnum] The index of the bit to modify
+    #
+    # @return [Fixnum] The bitset's integer representation after being modified
     def clear(bit)
-      set(bit, false) 
+      set(bit, false)
     end
 
+    # Checks if a bit at an index is set to 1
+    #
+    # @param bit [Fixnum] Index of bit to check
+    #
+    # @return [Boolean] Whether or not the bit is set to one
     def set?(bit)
-      bit = convert_bit(bit) 
+      bit = convert_bit(bit)
       intersect(bit) == bit
     end
 
+    # Checks if all of another bitset's flipped bits are flipped in this one
+    #
+    # @param other [Bitset] Bitset use for inclusion check
+    #
+    # @return [Boolean] Whether or not all bits are flipped in both
     def include?(other)
       set_indexes & other.set_indexes == other.set_indexes
     end
 
+    # Perform a bitwise AND
+    #
+    # @param other [Bitset or Fixnum] Other object to use for AND
+    #
+    # @return [Fixnum] Bits after operation
     def intersect(other)
-      @bits & bits_from_object(other) 
+      @bits & bits_from_object(other)
     end
     alias_method :&, :intersect
 
-    def intersect?(other)
-      if other_bits = bits_from_object(other) > 0
-        intersect(other_bits) == other_bits
-      else
-        false
-      end
-    end
-
+    # Perform a bitwise NOT on the current bitset
+    #
+    # @return [Fixnum] Bits after operation
     def not
       ~@bits
     end
     alias_method :~, :not
 
+    # Perform a bitwise XOR
+    #
+    # @param other [Bitset or Fixnum] Other object to use for XOR
+    #
+    # @return [Fixnum] Bits after operation
     def xor(other)
-      @bits ^ bits_from_object(other) 
+      @bits ^ bits_from_object(other)
     end
     alias_method :^, :xor
 
+    # Perform a bitwise OR
+    #
+    # @param other [Bitset or Fixnum] Other object to use for OR
+    #
+    # @return [Fixnum] Bits after operation
     def union(other)
       @bits | bits_from_object(other)
     end
     alias_method :|, :union
 
+    # Return the binary representation of the bitset
+    #
+    # @return [String] Binary of current bits
     def to_s
-      @bits.to_s(2)  
+      @bits.to_s(2)
     end
 
+    # Return Integer representation of the bitset
+    #
+    # @return [Fixnum] Integer of current bits
     def to_i
       @bits.to_i
     end
 
+    # Return Float representation of the bitset
+    #
+    # @return [Float] Float of current bits
     def to_f
       @bits.to_f
     end
 
+    # Check for a bit at an index to be set to 1
+    #
+    # @param index [Fixnum] Index of bit to check
+    #
+    # @return [Boolean] Whether or not the bit is set to 1
     def [](index)
       set?(index)
     end
 
+    # Set a bit at an index to 0 or 1
+    #
+    # @param index [Fixnum] Index of bitset to set
+    # @param value [Boolean] Whether to set the bit to 0 or 1
+    #
+    # @return [Fixnum] The bitset's integer representation after being modified
     def []=(index, value)
       set(index, value)
     end
 
+    # Check if other bitset's bits match the current ones
+    #
+    # @param other [Bitset] Other bitset
+    #
+    # @return [Boolean] Whether or not the bits match
     def ==(other)
       @bits == other.bits
     end

data/lib/darkholme/component.rb

@@ -1,14 +1,23 @@
 module Darkholme
+  # Top-level class for storing data on an Entity that a System uses
   class Component
     @next_bit = 0
     @bits = {}
 
+    # Get a unique bit for a Component class
+    #
+    # @param klass [Class] The class to generate (or look up) the bit for
+    #
+    # @return [Fixnum] The bit for that class
     def self.bit_for(klass)
       @bits[klass] ||= @next_bit += 1
     end
 
+    # Get the current instance's class' bit
+    #
+    # @return [Fixnum] The bit for the instance's class
     def bit
-      Component.bit_for(self.class) 
+      Component.bit_for(self.class)
     end
   end
 end

data/lib/darkholme/engine.rb

@@ -1,39 +1,87 @@
 module Darkholme
+  # An Engine contains all of a game's entities, components, and systems.
+  # Usually only one is needed for your entire game, although no limitation
+  # is hardcoded. Use at your discretion.
   class Engine
-    attr_reader :systems, :entities
+    attr_reader :systems, :entities, :families
 
+    # Create a new engine with empty systems and entities
+    #
+    # @return [Engine] The new Engine
     def initialize
       @systems = {}
       @families = {}
       @entities = Set.new
     end
 
+    # Add an entity to the engine (with callbacks). Once added,
+    # the entity is available for use by systems during each
+    # update loop.
+    #
+    # @param entity [Entity] The entity to add
+    #
+    # @return Result of entity#added_to_engine
     def add_entity(entity)
       @entities << entity
       entity.added_to_engine self
     end
 
+    # Remove an entity from the engine (with callbacks). Once removed,
+    # the entity will no longer be updated during the update loop
+    #
+    # @param entity [Entity] The entity to remove
+    #
+    # @return Result of entity#removed_from_engine
     def remove_entity(entity)
       @entities.delete entity
       entity.removed_from_engine self
     end
 
+    # Add a system to be updated each frame
+    #
+    # @param system [System] The system to add
+    #
+    # @return Result of system#added_to_engine
     def add_system(system)
       @systems[system.class] = system
       system.added_to_engine self
     end
 
-    def remove_system(systemClass)
-      system = @systems.delete systemClass 
+    # Remove a system from the engine. It will no longer be updated
+    # each frame
+    #
+    # @param system_class [Class] Class of System to remove
+    #
+    # @return Result of system#removed_from_engine
+    def remove_system(system_class)
+      system = @systems.delete system_class
       system.removed_from_engine(self) if system
     end
 
-    def system(systemClass)
-      @systems[systemClass]
+    # Retrieve a system added to the engine by its class
+    #
+    # @param system_class [Class] Class of the system to get
+    #
+    # @example Standard usage
+    #   engine.system_for(MySystem)
+    #
+    # @return [System] A System instance, if found
+    def system_for(system_class)
+      @systems[system_class]
     end
 
+    # Retrieve all entities matching Family provided
+    #
+    # @param family [Family] Family to use when checking entities
+    #
+    # @example Standard usage
+    #   engine.entities_for_family(
+    #     Family.for(MyComponent, AnotherComponent)
+    #   )
+    #
+    # @return [Array<Entity>] All entities matching provided Family
     def entities_for_family(family)
-      @families[family.index] ||= begin
+      @families[family] ||= begin
         Set.new.tap do |entities|
           @entities.each do |entity|
             entities << entity if family.member?(entity)
@@ -42,9 +90,41 @@ module Darkholme
       end
     end
 
+    # Update all systems within engine. This should called once per
+    # frame in game.
+    #
+    # @param delta [Float] Time between last frame and this one
+    #
+    # @example Standard usage
+    #   engine.update(0.0008)
     def update(delta)
       @systems.each {|klass, system| system.update(delta) }
     end
 
+    # A callback called every time an entity added to the engine
+    # has a component added. Updates all associated families
+    def component_added(entity, component)
+      @families.each do |family, entities|
+        unless entity.family_bits.set?(family.index)
+          if family.member?(entity)
+            entities << entity
+            entity.family_bits.set(family.index)
+          end
+        end
+      end
+    end
+
+    # A callback called every time an entity added to the engine
+    # has a component removed. Updates all associated families
+    def component_removed(entity, component)
+      @families.each do |family, entities|
+        if entity.family_bits.set?(family.index)
+          unless family.member?(entity)
+            entities.delete(entity)
+            entity.family_bits.clear(family.index)
+          end
+        end
+      end
+    end
   end
 end

data/lib/darkholme/entity.rb

@@ -1,41 +1,75 @@
 module Darkholme
+  # An Entity contains Components, which hold data which is manipulated
+  # by a System
   class Entity
-    attr_accessor :engine, :components, :component_bits
+    attr_accessor :engine, :components, :component_bits, :family_bits
 
+    # Create a new Entity
+    #
+    # @return [Entity] The new Entity
     def initialize
       self.components = {}
       self.component_bits = Bitset.new
+      self.family_bits = Bitset.new
       self.engine = nil
     end
 
+    # Callback called after the entity has been added to an Engine
+    #
+    # @param engine [Engine] The engine the system was added to
     def added_to_engine(engine)
       self.engine = engine
     end
 
+    # Callback called after the engine has been removed from an Engine
+    #
+    # @param engine [Engine] The engine the entity was removed from
     def removed_from_engine(engine)
       self.engine = nil
     end
 
+    # Add a component to an entity
+    #
+    # @param component [Component] The component being added
+    #
+    # @return [Component] The component that was added
     def add_component(component)
       self.components[component.class] = component
       self.component_bits.set(component.bit)
+      self.engine.component_added(self, component) if self.engine
 
-      component 
+      component
     end
 
+    # Remove a component from an entity
+    #
+    # @param component_class [Class] The class of the component being removed
+    #
+    # @return [Component] The component that was removed
     def remove_component(component_class)
       if removed_component = component_for(component_class)
         self.component_bits.clear(removed_component.bit)
         self.components.delete(component_class)
+        self.engine.component_removed(self, removed_component) if self.engine
       end
 
       removed_component
     end
 
+    # Check to see if an entity contains a type of component
+    #
+    # @param component_class [Class] The class of the component to check for
+    #
+    # @return [Boolean] Whether or not the entity has the component
     def has_component?(component_class)
       self.components.include? component_class
     end
 
+    # Retrieve a component of a certain class from an entity
+    #
+    # @param component_class [Class] The class of the component to get
+    #
+    # @return [Component] The component, if present
     def component_for(component_class)
       self.components[component_class]
     end

data/lib/darkholme/family.rb

@@ -1,5 +1,6 @@
 module Darkholme
-  class Family 
+  # Used by systems and engines to get related entities for processing
+  class Family
     @next_index = 0
     @families = {}
 
@@ -9,6 +10,13 @@ module Darkholme
 
     attr_reader :index, :bits
 
+    # Get a family for matching entities with a specific
+    # list of components present
+    #
+    # @param component_classes [Array<Class>] List of Component classes to
+    #   check for
+    #
+    # @return [Family] The Family instance for that list of Components
     def self.for(*component_classes)
       bits = Bitset.new
       component_classes.each do |klass|
@@ -21,6 +29,11 @@ module Darkholme
       end
     end
 
+    # Check if an Entity has all the required Components for the Family
+    #
+    # @param entity [Entity] The entity to check for membership
+    #
+    # @return [Boolean] Whether or not the entity is a member of the Family
     def member?(entity)
       entity.component_bits.include?(bits)
     end

data/lib/darkholme/iterating_system.rb

@@ -1,5 +1,15 @@
 module Darkholme
+  # A subclass of System, IteratingSystem automatically loops through entities
+  # belonging to it and calls #process on them, along with a before and after
+  # callback
   class IteratingSystem < System
+    # Called by the engine, this calls #before_processing, then #process on
+    # each entity, then #after_processing
+    #
+    # @param delta [Float] The difference in time between the last frame
+    #   and this one
+    # 
+    # @return The result of after_processing
     def update(delta)
       before_processing
       entities.each do |entity|
@@ -8,13 +18,22 @@ module Darkholme
       after_processing
     end
 
+    # Called on each entity in the collection. This where the various
+    # components' data will be manipulated. This must be overridden by
+    # the subclass.
+    #
+    # @param entity [Entity] The entity being manipulated
+    # @param delta [Float] The difference in time between the last frame
+    #   and this one
     def process(entity, delta)
       raise NotImplementedError.new("You must override #process(entity, delta)")
     end
 
+    # Called once a frame before the entities are looped over and processed
     def before_processing
     end
 
+    # Called once a frame after the entities are looped over and processed
     def after_processing
     end
   end

data/lib/darkholme/system.rb

@@ -1,31 +1,61 @@
 module Darkholme
+  # Updated every frame by the engine, a System manipulates and uses the
+  # data contained within a component
   class System
     class << self
       attr_reader :family
 
+      # Set the family for a System. Call this from the body of the
+      # class.
+      #
+      # @param component_classes [Array<Class>] List of component classes the system is
+      #
+      # @example Standard usage
+      #   class MySystem < Darkholme::System
+      #     has_family MyComponent, AnotherComponent, LastComponent
+      #   end
+      #
+      # @return [Family] The family for the classes
       def has_family(*component_classes)
-        @family = Family.for(*component_classes) 
+        @family = Family.for(*component_classes)
       end
     end
 
+    # @!attribute engine [Engine] The engine this system belongs to
     attr_accessor :engine
 
+    # Called once per frame by the engine. This must be overriden
+    # by the subclass.
+    #
+    # @param delta [Float] Difference in time between the last frame and this one
     def update(delta)
       raise NotImplementedError.new("You must override #update(delta)")
     end
 
+    # Callback called after the system has been added to an Engine
+    #
+    # @param engine [Engine] The engine the system was added to
     def added_to_engine(engine)
       self.engine = engine
     end
 
+    # Callback called after the system has been removed from an Engine
+    #
+    # @param engine [Engine] The engine the system was removed from
     def removed_from_engine(engine)
       self.engine = nil if self.engine == engine
     end
 
+    # An Array of all the entities this system is interested in
+    #
+    # @return [Array<Entity>] All the entities with matching components
     def entities
       engine.entities_for_family(family)
     end
 
+    # Get the system's Family instance
+    #
+    # @return [Family] The system's family, as defined by #has_family
     def family
       self.class.family
     end

data/spec/lib/darkholme/engine_spec.rb

@@ -4,23 +4,23 @@ module Darkholme
   describe Engine do
     subject { Engine.new }
     let(:entity) { MockEntity.new }
-    let(:system) { MockSystem.new } 
+    let(:system) { MockSystem.new }
 
     describe "with entities" do
       it "can add them" do
         expect {
           subject.add_entity(entity)
-        }.to change { subject.entities.count }.from(0).to(1) 
+        }.to change { subject.entities.count }.from(0).to(1)
       end
 
       it "can remove them" do
         subject.add_entity(entity)
 
-        expect { 
+        expect {
           subject.remove_entity(entity)
         }.to change { subject.entities.count }.from(1).to(0)
       end
-      
+
       it "can find them by family" do
         entity.add_component(MockComponent.new)
         subject.add_entity(entity)
@@ -53,6 +53,28 @@ module Darkholme
         subject.update(:delta)
       end
     end
+
+    describe "with callbacks" do
+      let(:family) { Family.for(MockComponent) }
+      it "updates families upon component addition" do
+        subject.families[family] = []
+        entity.engine = subject
+
+        expect(subject.families[family]).not_to include(entity)
+        entity.add_component MockComponent.new
+        expect(subject.families[family]).to include(entity)
+      end
+
+      it "updates families upon component removal" do
+        subject.families[family] = [entity]
+        entity.engine = subject
+        entity.add_component MockComponent.new
+
+        expect(subject.families[family]).to include(entity)
+        entity.remove_component MockComponent
+        expect(subject.families[family]).not_to include(entity)
+      end
+    end
   end
 end
 

data/spec/lib/darkholme/entity_spec.rb

@@ -41,8 +41,17 @@ module Darkholme
 
           subject.add_component(component)
         end
+
+        it "notifies the engine" do
+          subject.engine = Engine.new
+          expect(subject.engine).to receive(:component_added).with(
+            subject, component
+          )
+
+          subject.add_component(component)
+        end
       end
-     
+
       describe "removing one" do
         let!(:added) { subject.add_component(component) }
 
@@ -62,8 +71,17 @@ module Darkholme
 
           subject.remove_component(component.class)
         end
+
+        it "notifies the engine" do
+          subject.engine = Engine.new
+          expect(subject.engine).to receive(:component_removed).with(
+            subject, component
+          )
+
+          subject.remove_component(component.class)
+        end
       end
-      
+
       it "returns a component instance when asked for one" do
         subject.add_component(component)
         expect(subject.component_for(component.class)).to be_a MockComponent

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: darkholme
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Massive Danger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-23 00:00:00.000000000 Z
+date: 2014-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry