class Peregrine::EntityManager
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
Attributes
Array of entities owned by this EntityManager
.
Array of Systems operating within this EntityManager
.
Public Class Methods
Creates a new EntityManager
instance. Yields the newly created instance if a block is given.
# File lib/peregrine/entity_manager.rb, line 70 def initialize @entities = [].extend(Collections::Common, Collections::Composite) @systems = [].extend(Collections::Common, Collections::Systemic) yield self if block_given? end
Public Instance Methods
Adds the given Entity
instances (or instantiated Entity
constants) to the EntityManager
. Returns the array of managed Entity
objects.
# File lib/peregrine/entity_manager.rb, line 97 def add_entities(*entities) entities.each do |entity| entity = entity.new if entity.class == Class @entities.push(entity) end @entities end
Unwraps the given Package
, adding any included System
and Entity
instances directly to the EntityManager
. Returns true
if the package was unwrapped successfully, false
otherwise.
# File lib/peregrine/entity_manager.rb, line 160 def add_package(package) return false unless package.respond_to?(:unwrap) package.unwrap.each do |item| add_system(item) if item.kind_of?(Peregrine::System) add_entity(item) if item.kind_of?(Peregrine::Entity) end true 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
.
# File lib/peregrine/entity_manager.rb, line 130 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
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.
# File lib/peregrine/entity_manager.rb, line 121 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
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
.
# File lib/peregrine/entity_manager.rb, line 80 def process @systems.each { |system| system.process if system.enabled? } end
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.
# File lib/peregrine/entity_manager.rb, line 109 def remove_entities!(*entities) removed = [] @entities.reject! do |entity| entities.include?(entity) ? removed.push(entity) : false end removed.extend(Collections::Common, Collections::Composite) end
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.
# File lib/peregrine/entity_manager.rb, line 146 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
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.
# File lib/peregrine/entity_manager.rb, line 88 def spawn(*arguments) entity = Peregrine::Entity.new(*arguments) yield entity if block_given? @entities.push(entity) entity end
Presents a human-readable summary of the EntityManager
.
# File lib/peregrine/entity_manager.rb, line 170 def to_s "Entity Manager '#{name}' #{id} " << "(#{@entities.size} Entities, #{@systems.size} Systems)" end