chione 0.3.0 → 0.4.0

data/lib/chione/entity.rb

@@ -6,12 +6,15 @@ require 'loggability'
 require 'securerandom'
 
 require 'chione' unless defined?( Chione )
+require 'chione/mixins'
 
 # The Entity (identity) class
 class Chione::Entity
 	extend Loggability,
 	       Deprecatable
 
+	include Chione::Inspection
+
 	# Loggability API -- send logs to the Chione logger
 	log_to :chione
 
@@ -25,9 +28,8 @@ class Chione::Entity
 	### Create a new Entity for the specified +world+, and use the specified +id+ if
 	### given. If no +id+ is given, one will be automatically generated.
 	def initialize( world, id=nil )
-		@world      = world
-		@id         = id || self.class.make_new_id
-		@components = {}
+		@world = world
+		@id    = id || self.class.make_new_id
 	end
 
 
@@ -41,42 +43,50 @@ class Chione::Entity
 	# The World the Entity belongs to
 	attr_reader :world
 
-	##
-	# The Hash of this entity's Components
-	attr_reader :components
+
+	### Return the components that the entity's World has registered for it as a Hash
+	### keyed by the Component class.
+	def components
+		return self.world.components_for( self )
+	end
 
 
-	### Add the specified +component+ to the entity. It will replace any existing component
-	### of the same type.
-	def add_component( component )
-		component = Chione::Component( component )
-		self.components[ component.class ] = component
-		self.world.add_component_for( self, component )
+	### Add the specified +component+ to the entity. The +component+ can be a
+	### subclass of Chione::Component, an instance of such a subclass, or the name
+	### of a subclass. It will replace any existing component of the same type.
+	def add_component( component, **init_values )
+		self.world.add_component_to( self, component, init_values )
 	end
 
 
-	### Fetch the first Component of the specified +types+ that belongs to the entity. If the
-	### Entity doesn't have any of the specified types of Component, raises a KeyError.
-	def find_component( *types )
-		found_type = types.find {|type| self.components[type] } or
-			raise KeyError, "entity %s doesn't have any of %p" % [ self.id, types ]
-		return self.components[ found_type ]
+	### Fetch the component of the specified +component_class+ that corresponds with the
+	### receiving entity. Returns +nil+ if so much component exists.
+	def get_component( component_class )
+		return self.world.get_component_for( self, component_class )
 	end
-	alias_method :get_component, :find_component
-	deprecate :get_component, message: 'Use #find_component instead', removal_version: '1.0'
 
 
-	### Returns +true+ if this entity has the specified +component+.
-	def has_component?( component )
-		return self.components.key?( component )
+	### Remove the component of the specified +component_class+ that corresponds with the
+	### receiving entity. Returns the component instance if it was removed, or +nil+ if no
+	### Component of the specified type was registered to the entity.
+	def remove_component( component_class )
+		return self.world.remove_component_from( self, component_class )
 	end
 
 
-	### Return the Entity as a human-readable string suitable for debugging.
-	def inspect
-		return "#<%p:%0#x ID=%s (%s)>" % [
-			self.class,
-			self.object_id * 2,
+	### Returns +true+ if this entity has a component of the specified +component_class+.
+	def has_component?( component_class )
+		return self.world.has_component_for?( self, component_class )
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return the detailed part of the Entity's #inspect output
+	def inspect_details
+		return "ID=%s (%s)" % [
 			self.id,
 			self.components.keys.map( &:name ).sort.join( '+' )
 		]

data/lib/chione/fixtures.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'faker'
+require 'fluent_fixtures'
+
+require 'chione' unless defined?( Chione )
+
+
+module Chione::Fixtures
+	extend FluentFixtures::Collection
+
+	# Set the path to use when finding fixtures for this collection
+	fixture_path_prefix 'chione/fixtures'
+
+end # module Chione
+

data/lib/chione/fixtures/entities.rb

@@ -0,0 +1,32 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'faker'
+
+require 'chione/fixtures' unless defined?( Chione::Fixtures )
+require 'chione/entity'
+
+
+# Entity fixtures
+module Chione::Fixtures::Entities
+	extend Chione::Fixtures
+
+	fixtured_class Chione::Entity
+
+	base :entity
+
+	decorator :with_id do |id|
+		@id = id
+	end
+
+
+	decorator :with_components do |*components|
+		components.each do |comp|
+			self.add_component( comp )
+		end
+	end
+
+end # module Chione::Fixtures::Entities
+
+
+

data/lib/chione/iterating_system.rb

@@ -0,0 +1,35 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'chione'
+require 'chione/system'
+
+
+
+# Process all entities matching an aspect iteratively for every World timing
+# loop iteration.
+class Chione::IteratingSystem < Chione::System
+
+
+	every_tick do |*|
+		world = self.world
+
+		self.class.aspects.each do |name, aspect|
+			self.log.debug "Iterating over entities with '%s'" % [ name ]
+			world.entities_with( aspect ).each do |entity|
+				self.process( name, entity, world.components_for(entity) )
+			end
+		end
+
+	end
+
+
+	### Process the given +components+ (which match the system's Aspect) for the
+	### specified +entity_id+. Concrete subclasses are required to override this.
+	def process( aspect_name, entity_id, components )
+		raise NotImplementedError, "%p does not implement #%s" % [ self.class, __method__ ]
+	end
+
+
+end # class Chione::IteratingSystem
+

data/lib/chione/manager.rb

@@ -5,6 +5,7 @@ require 'pluggability'
 require 'loggability'
 
 require 'chione' unless defined?( Chione )
+require 'chione/mixins'
 
 
 # The Manager class
@@ -12,6 +13,9 @@ class Chione::Manager
 	extend Loggability,
 	       Pluggability
 
+	include Chione::Inspection
+
+
 	# Loggability API -- send logs to the Chione logger
 	log_to :chione
 
@@ -46,4 +50,15 @@ class Chione::Manager
 		raise NotImplementedError, "%p does not implement required method #stop" % [ self.class ]
 	end
 
+
+	#########
+	protected
+	#########
+
+	### Return the detail part of the inspection string.
+	def inspect_details
+		return "for %p:%#016x" % [ self.world.class, self.world.object_id * 2 ]
+	end
+
+
 end # class Chione::Manager

data/lib/chione/mixins.rb

@@ -88,4 +88,26 @@ module Chione
 
 	end # module MethodUtilities
 
+
+	# An extensible #inspect for Chione objects.
+	module Inspection
+
+		### Return a human-readable representation of the object suitable for debugging.
+		def inspect
+			return "#<%p:%#016x %s>" % [
+				self.class,
+				self.object_id * 2,
+				self.inspect_details,
+			]
+		end
+
+
+		### Return the detail portion of the inspect output for this object.
+		def inspect_details
+			return ''
+		end
+
+	end # module Inspection
+
+
 end # module Chione

data/lib/chione/system.rb

@@ -15,6 +15,19 @@ class Chione::System
 	       Pluggability,
 	       Chione::MethodUtilities
 
+	include Chione::Inspection
+
+
+	# A Hash that auto-vivifies only its :default key
+	DEFAULT_ASPECT_HASH = Hash.new do |h,k|
+		if k == :default
+			h[k] = Chione::Aspect.new
+		else
+			nil
+		end
+	end
+
+
 	# Loggability API -- send logs to the Chione logger
 	log_to :chione
 
@@ -22,25 +35,73 @@ class Chione::System
 	plugin_prefixes 'chione/system'
 
 
+	##
+	# The Hash of Chione::Aspects that describe entities this system is interested
+	# in, keyed by name (a Symbol). A System which declares no aspects will have a
+	# +:default+ Aspect which matches all entities.
+	singleton_attr_reader :aspects
+
+	##
+	# Event handler tuples (event name, callback) that should be registered when the
+	# System is started.
+	singleton_attr_reader :event_handlers
+
+
 	### Add the specified +component_types+ to the Aspect of this System as being
 	### required in any entities it processes.
-	def self::aspect( *required, all_of: nil, one_of: nil, none_of: nil )
-		@aspect ||= Chione::Aspect.new
+	def self::aspect( name, *required, all_of: nil, one_of: nil, none_of: nil )
+		aspect = Chione::Aspect.new
 
 		all_of = required + Array( all_of )
 
-		@aspect = @aspect.with_all_of( all_of )
-		@aspect = @aspect.with_one_of( one_of )   if one_of
-		@aspect = @aspect.with_none_of( none_of ) if none_of
+		aspect = aspect.with_all_of( all_of )
+		aspect = aspect.with_one_of( one_of )   if one_of
+		aspect = aspect.with_none_of( none_of ) if none_of
 
-		return @aspect
+		self.aspects[ name ] = aspect
+	end
+
+
+	### Declare a block that is called once whenever an event matching +event_name+ is
+	### broadcast to the World.
+	def self::on( event_name, &block )
+		raise LocalJumpError, "no block given" unless block
+		raise ArgumentError, "callback has wrong arity" unless block.arity >= 2 || block.arity < 0
+
+		method_name = "on_%s_event" % [ event_name.tr('/', '_') ]
+		self.log.debug "Making handler method #%s for %s events out of %p" %
+			[ method_name, event_name, block ]
+		define_method( method_name, &block )
+
+		self.event_handlers << [ event_name, method_name ]
+	end
+
+
+	### Declare a block that is called once every tick for each entity that matches the given
+	### +aspect+.
+	def self::every_tick( &block )
+		return self.on( 'timing' ) do |event_name, payload|
+			self.instance_exec( *payload, &block )
+		end
+	end
+
+
+	### Add some per-subclass data structures to inheriting +subclass+es.
+	def self::inherited( subclass )
+		super
+		subclass.instance_variable_set( :@aspects, DEFAULT_ASPECT_HASH.clone )
+		subclass.instance_variable_set( :@event_handlers, self.event_handlers&.dup || [] )
 	end
-	singleton_method_alias :for_entities_that_have, :aspect
 
 
 	### Create a new Chione::System for the specified +world+.
 	def initialize( world, * )
 		@world  = world
+		@aspect_entities = self.class.aspects.each_with_object( {} ) do |(aspect_name, aspect), hash|
+			matching_set = world.entities_with( aspect )
+			self.log.debug "Initial Set with the %s aspect: %p" % [ aspect_name, matching_set]
+			hash[ aspect_name ] = matching_set
+		end
 	end
 
 
@@ -48,25 +109,89 @@ class Chione::System
 	public
 	######
 
+	##
 	# The World which the System belongs to
 	attr_reader :world
 
+	##
+	# The Hash of Sets of entity IDs which match the System's aspects, keyed by aspect name.
+	attr_reader :aspect_entities
+
 
 	### Start the system.
 	def start
-		self.log.info "Starting the %p" % [ self.class ]
+		self.log.info "Starting the %p system; %d event handlers to register" %
+			[ self.class, self.class.event_handlers.length ]
+		self.class.event_handlers.each do |event_name, method_name|
+			callback = self.method( method_name )
+			self.log.info "Registering %p as a callback for '%s' events." % [ callback, event_name ]
+			self.world.subscribe( event_name, callback )
+		end
 	end
 
 
 	### Stop the system.
 	def stop
+		self.class.event_handlers.each do |_, method_name|
+			callback = self.method( method_name )
+			self.log.info "Unregistering subscription for %p." % [ callback ]
+			self.world.unsubscribe( callback )
+		end
+	end
+
+
+	### Return an Enumerator that yields the entities which match the given +aspect_name+.
+	def entities( aspect_name=:default )
+		return self.aspect_entities[ aspect_name ].to_enum( :each )
+	end
+
+
+	### Entity callback -- called whenever an entity has a component added to it or
+	### removed from it. Calls the appropriate callback (#inserted or #removed) if
+	### the component change caused it to belong to or stop belonging to one of the
+	### system's aspects.
+	def entity_components_updated( entity_id, components_hash )
+		self.class.aspects.each do |aspect_name, aspect|
+			entity_ids = self.aspect_entities[ aspect_name ]
+
+			if aspect.matches?( components_hash )
+				self.inserted( aspect_name, entity_id, components_hash ) if
+					entity_ids.add?( entity_id )
+			else
+				self.removed( aspect_name, entity_id, components_hash ) if
+					entity_ids.delete?( entity_id )
+			end
+		end
+	end
+
+
+	### Entity callback -- called whenever an entity has a component added to it
+	### that makes it start matching an aspect of the receiving System. The
+	### +aspect_name+ is the name of the Aspect it now matches, and the +components+
+	### are a Hash of the entity's components keyed by Class. By default this is a
+	### no-op.
+	def inserted( aspect_name, entity_id, components )
+		self.log.debug "Entity %s now matches the %s aspect." % [ entity_id, aspect_name ]
 	end
 
 
-	### Return an Enumerator that yields the entities which this system operators
-	### over.
-	def entities
-		return self.world.entities_for( self )
+	### Entity callback -- called whenever an entity has a component removed from it
+	### that makes it stop matching an aspect of the receiving System. The
+	### +aspect_name+ is the name of the Aspect it no longer matches, and the
+	### +components+ are a Hash of the entity's components keyed by Class. By
+	### default this is a no-op.
+	def removed( aspect_name, entity_id, components )
+		self.log.debug "Entity %s no longer matches the %s aspect." % [ entity_id, aspect_name ]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return the detail part of the inspection string.
+	def inspect_details
+		return "for %p:%#016x" % [ self.world.class, self.world.object_id * 2 ]
 	end
 
 end # class Chione::System

data/lib/chione/world.rb

@@ -42,9 +42,7 @@ class Chione::World
 		@systems       = {}
 		@managers      = {}
 
-		@subscriptions = Hash.new do |h,k|
-			h[ k ] = Set.new
-		end
+		@subscriptions = Hash.new {|h,k| h[k] = Set.new }
 		@defer_events  = true
 		@deferred_events = []
 
@@ -52,8 +50,9 @@ class Chione::World
 		@world_threads = ThreadGroup.new
 
 		@entities_by_component = Hash.new {|h,k| h[k] = Set.new }
+		@components_by_entity = Hash.new {|h, k| h[k] = {} }
 
-		@timing_event_count = 0
+		@tick_count = 0
 	end
 
 
@@ -63,7 +62,7 @@ class Chione::World
 
 	##
 	# The number of times the event loop has executed.
-	attr_reader :timing_event_count
+	attr_accessor :tick_count
 
 	##
 	# The Hash of all Entities in the World, keyed by ID
@@ -85,6 +84,16 @@ class Chione::World
 	# The Thread object running the World's IO reactor loop
 	attr_reader :main_thread
 
+	##
+	# The Hash of Sets of Entities which have a particular component, keyed by
+	# Component class.
+	attr_reader :entities_by_component
+
+	##
+	# The Hash of Hashes of Components which have been added to an Entity, keyed by
+	# the Entity's ID and the Component class.
+	attr_reader :components_by_entity
+
 	##
 	# The Hash of event subscription callbacks registered with the world, keyed by
 	# event pattern.
@@ -120,6 +129,15 @@ class Chione::World
 	end
 
 
+	### Step the world +delta_seconds+ into the future.
+	def tick( delta_seconds=1.0/60.0 )
+		self.publish( 'timing', delta_seconds, self.tick_count )
+		self.publish_deferred_events
+
+		self.tick_count += 1
+	end
+
+
 	### Start any Managers registered with the world.
 	def start_managers
 		self.log.info "Starting %d Managers" % [ self.managers.length ]
@@ -168,7 +186,7 @@ class Chione::World
 
 	### Returns +true+ if the World is running (i.e., if #start has been called)
 	def running?
-		return self.started? && self.timing_event_count.nonzero?
+		return self.started? && self.tick_count.nonzero?
 	end
 
 
@@ -238,6 +256,7 @@ class Chione::World
 
 	### Send any deferred events to subscribers.
 	def publish_deferred_events
+		self.log.debug "Publishing %d deferred events" % [ self.deferred_events.length ]
 		while event = self.deferred_events.shift
 			self.call_subscription_callbacks( *event )
 		end
@@ -273,6 +292,10 @@ class Chione::World
 	end
 
 
+	#
+	# :section: Entity API
+	#
+
 	### Return a new Chione::Entity for the receiving World, using the optional
 	### +archetype+ to populate it with components if it's specified.
 	def create_entity( archetype=nil )
@@ -304,7 +327,8 @@ class Chione::World
 			self.has_entity?( entity )
 
 		self.publish( 'entity/destroyed', entity )
-		@entities_by_component.each_value {|set| set.delete(entity) }
+		self.entities_by_component.each_value {|set| set.delete(entity.id) }
+		self.components_by_entity.delete( entity.id )
 		@entities.delete( entity.id )
 	end
 
@@ -320,74 +344,171 @@ class Chione::World
 	end
 
 
-	### Register the specified +component+ as having been added to the specified
-	### +entity+.
-	def add_component_for( entity, component )
+	#
+	# :section: Component API
+	#
+
+	### Add the specified +component+ to the specified +entity+.
+	def add_component_to( entity, component, **init_values )
+		entity = entity.id if entity.respond_to?( :id )
+		component = Chione::Component( component, init_values )
+		component.entity_id = entity
+
 		self.log.debug "Adding %p for %p" % [ component.class, entity ]
-		@entities_by_component[ component.class ].add( entity )
+		self.entities_by_component[ component.class ].add( entity )
+		component_hash = self.components_by_entity[ entity ]
+		component_hash[ component.class ] = component
+
+		self.update_entity_caches( entity, component_hash )
 	end
+	alias_method :add_component_for, :add_component_to
 
 
-	### Return an Enumerator of the Entities that have a Component composition that
-	### is compatible with the specified +system+'s aspect.
-	def entities_for( system )
-		system = system.class unless system.is_a?( Class )
-		return self.entities_with( system.aspect ).to_enum
+	### Return a Hash of the Component instances associated with +entity+, keyed by
+	### their class.
+	def components_for( entity )
+		entity = entity.id if entity.respond_to?( :id )
+		return self.components_by_entity[ entity ].dup
 	end
 
 
-	### Return an Array of all entities that match the specified +aspect+.
-	def entities_with( aspect )
-		initial_set = if aspect.one_of.empty?
-				@entities_by_component.values
-			else
-				@entities_by_component.values_at( *aspect.one_of )
-			end
+	### Return the Component instance of the specified +component_class+ that's
+	### associated with the given +entity+, if it has one.
+	def get_component_for( entity, component_class )
+		entity = entity.id if entity.respond_to?( :id )
+		return self.components_by_entity[ entity ][ component_class ]
+	end
+
+
+	### Remove the specified +component+ from the given +entity+. If +component+ is
+	### a Component subclass, any instance of it will be removed. If it's a
+	### Component instance, it will be removed iff it is the same instance associated
+	### with the given +entity+.
+	def remove_component_from( entity, component )
+		entity = entity.id if entity.respond_to?( :id )
+		if component.is_a?( Class )
+			self.entities_by_component[ component ].delete( entity )
+			component_hash = self.components_by_entity[ entity ]
+			component_hash.delete( component )
+			self.update_entity_caches( entity, component_hash )
+		else
+			self.remove_component_from( entity, component.class ) if
+				self.has_component_for?( entity, component )
+		end
+	end
+	alias_method :remove_component_for, :remove_component_from
 
-		with_one = initial_set.reduce( :| )
-		with_all = @entities_by_component.values_at( *aspect.all_of ).reduce( with_one, :& )
-		without_any = @entities_by_component.values_at( *aspect.none_of ).reduce( with_all, :- )
 
-		return without_any
+	### Return +true+ if the specified +entity+ has the given +component+. If
+	### +component+ is a Component subclass, any instance of it will test +true+. If
+	### +component+ is a Component instance, it will only test +true+ if the
+	### +entity+ is associated with that particular instance.
+	def has_component_for?( entity, component )
+		entity = entity.id if entity.respond_to?( :id )
+		if component.is_a?( Class )
+			return self.components_by_entity[ entity ].key?( component )
+		else
+			return self.components_by_entity[ entity ][ component.class ] == component
+		end
 	end
 
 
+	#
+	# :section: System API
+	#
+
 	### Add an instance of the specified +system_type+ to the world and return it.
 	### It will replace any existing system of the same type.
 	def add_system( system_type, *args )
 		system_obj = system_type.new( self, *args )
-		@systems[ system_type ] = system_obj
+		self.systems[ system_type ] = system_obj
 
 		if self.running?
 			self.log.info "Starting %p added to running world." % [ system_type ]
 			system_obj.start
 		end
 
-		self.publish( 'system/added', system_type.name )
+		self.publish( 'system/added', system_obj )
 		return system_obj
 	end
 
 
+	### Remove the instance of the specified +system_type+ from the world and return
+	### it if it's been added. Returns +nil+ if no instance of the specified
+	### +system_type+ was added.
+	def remove_system( system_type )
+		system_obj = self.systems.delete( system_type ) or return nil
+
+		self.publish( 'system/removed', system_obj )
+
+		if self.running?
+			self.log.info "Stopping %p before being removed from runnning world." % [ system_type ]
+			system_obj.stop
+		end
+
+		return system_obj
+	end
+
+
+	### Return an Array of all entities that match the specified +aspect+.
+	def entities_with( aspect )
+		return aspect.matching_entities( self.entities_by_component )
+	end
+
+
+	#
+	# :section: Manager API
+	#
+
 	### Add an instance of the specified +manager_type+ to the world and return it.
 	### It will replace any existing manager of the same type.
 	def add_manager( manager_type, *args )
 		manager_obj = manager_type.new( self, *args )
-		@managers[ manager_type ] = manager_obj
+		self.managers[ manager_type ] = manager_obj
 
 		if self.running?
 			self.log.info "Starting %p added to running world." % [ manager_type ]
 			manager_obj.start
 		end
 
-		self.publish( 'manager/added', manager_type.name )
+		self.publish( 'manager/added', manager_obj )
+		return manager_obj
+	end
+
+
+	### Remove the instance of the specified +manager_type+ from the world and
+	### return it if it's been added. Returns +nil+ if no instance of the specified
+	### +manager_type+ was added.
+	def remove_manager( manager_type )
+		manager_obj = self.managers.delete( manager_type ) or return nil
+		self.publish( 'manager/removed', manager_obj )
+
+		if self.running?
+			self.log.info "Stopping %p removed from running world." % [ manager_type ]
+			manager_obj.stop
+		end
+
 		return manager_obj
 	end
 
 
+	# :section:
+
+
 	#########
 	protected
 	#########
 
+	### Update any entity caches in the system when an +entity+ has its +components+ hash changed.
+	def update_entity_caches( entity, components )
+		entity = entity.id if entity.respond_to?( :id )
+		self.log.debug "  updating entity cache for %p" % [ entity ]
+		self.systems.each_value do |sys|
+			sys.entity_components_updated( entity, components )
+		end
+	end
+
+
 	### The loop the main thread executes after the world is started. The default
 	### implementation just broadcasts the +timing+ event, so you will likely want to
 	### override this if the main thread should do something else.
@@ -396,22 +517,18 @@ class Chione::World
 		last_timing_event = Time.now
 		interval = self.class.timing_event_interval
 		self.defer_events = false
-		@timing_event_count = 0
+		self.tick_count = 0
 
 		loop do
 			previous_time, last_timing_event = last_timing_event, Time.now
-
-			self.publish( 'timing', last_timing_event - previous_time, @timing_event_count )
-			self.publish_deferred_events
-
-			@timing_event_count += 1
+			self.tick( last_timing_event - previous_time )
 			remaining_time = interval - (Time.now - last_timing_event)
 
 			if remaining_time > 0
 				sleep( remaining_time )
 			else
 				self.log.warn "Timing loop %d exceeded `timing_event_interval` (by %0.6fs)" %
-					[ @timing_event_count, remaining_time.abs ]
+					[ self.tick_count, remaining_time.abs ]
 			end
 		end