class Peregrine::System

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 })

Attributes

manager[RW]

The EntityManager object using this System instance.

Public Class Methods

new(manager = nil) { |self| ... } click to toggle source

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' ...>
# File lib/peregrine/system.rb, line 79
def initialize(manager = nil)
  @enabled = true
  @manager = manager
  @manager.systems.push(self) if @manager.respond_to?(:systems)
  yield self if block_given?
end

Public Instance Methods

disable() click to toggle source

Explicitly disables the System.

# File lib/peregrine/system.rb, line 111
def disable() @enabled = false end
enable() click to toggle source

Explicitly enables the System.

# File lib/peregrine/system.rb, line 108
def enable() @enabled = true end
enabled?() click to toggle source

Explicitly returns true if the System is enabled, false otherwise.

# File lib/peregrine/system.rb, line 114
def enabled?() @enabled ? true : false end
entities() { |entity| ... } click to toggle source

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.

# File lib/peregrine/system.rb, line 100
def entities
  return [] unless @manager.respond_to?(:entities)
  @manager.entities.select(&selector).each do |entity|
    yield entity if block_given?
  end
end
inspect()
Alias for: to_s
process() click to toggle source

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.

# File lib/peregrine/system.rb, line 120
def process() raise NotImplementedError end
selector() click to toggle source

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.

# File lib/peregrine/system.rb, line 90
def selector
  Proc.new { |entity| entity }
end
to_s() click to toggle source

Presents a human-readable summary of the System.

# File lib/peregrine/system.rb, line 123
def to_s
  status = enabled? ? '+' : '-'
  "#{status} System '#{name}' #{id} <#{manager.name} #{manager.id}>"
end
Also aliased as: inspect