Class: Peregrine::System

Inherits:
Object
  • Object
show all
Includes:
Features
Defined in:
lib/peregrine/system.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Features

included

Constructor Details

#initialize(manager = nil) {|_self| ... } ⇒ System

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' ...>

Yields:

  • (_self)

Yield Parameters:



79
80
81
82
83
84
 
# 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

Instance Attribute Details

#manager ⇒ Object

The EntityManager object using this System instance.



65
66
67
 
# File 'lib/peregrine/system.rb', line 65

def manager
  @manager
end

Instance Method Details

#disable ⇒ Object

Explicitly disables the System.



111
 
# File 'lib/peregrine/system.rb', line 111

def disable() @enabled = false end

#enable ⇒ Object

Explicitly enables the System.



108
 
# File 'lib/peregrine/system.rb', line 108

def enable() @enabled = true end

#enabled? ⇒ Boolean

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

Returns:

  • (Boolean) 


114
 
# File 'lib/peregrine/system.rb', line 114

def enabled?() @enabled ? true : false end

#entities ⇒ Object

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.



100
101
102
103
104
105
 
# 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

#process ⇒ Object

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.

Raises:

  • (NotImplementedError) 


120
 
# File 'lib/peregrine/system.rb', line 120

def process() raise NotImplementedError end

#selector ⇒ Object

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.



90
91
92
 
# File 'lib/peregrine/system.rb', line 90

def selector
  Proc.new { |entity| entity }
end

#to_s ⇒ Object Also known as: inspect

Presents a human-readable summary of the System.



123
124
125
126
 
# File 'lib/peregrine/system.rb', line 123

def to_s
  status = enabled? ? '+' : '-'
  "#{status} System '#{name}' #{id} <#{manager.name} #{manager.id}>"
end