chione 0.0.2

data/lib/chione/assemblage.rb

@@ -0,0 +1,64 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+
+require 'chione' unless defined?( Chione )
+
+
+# An Assemblage mixin for defining factories for commmon entity configurations.
+module Chione::Assemblage
+	extend Loggability
+
+	# Loggability API -- log to the chione logger
+	log_to :chione
+
+
+	### Extension callback -- add assemblage functionality to an extended +object+.
+	def self::extended( object )
+		super
+		object.extend( Loggability )
+		object.log_to( :chione )
+		object.components ||= {}
+	end
+
+
+	### Inclusion callback -- add the components from this assemblage to those in
+	### the specified +mod+.
+	def included( mod )
+		super
+		self.log.debug "Including %d components in %p" % [ self.components.length, mod ]
+		self.components.each do |component_type, args|
+			self.log.debug "Adding %p to %p from %p" % [ component_type, mod, self ]
+			mod.add( component_type, *args )
+		end
+	end
+
+
+	##
+	# The Hash of component types and initialization values to add to entities
+	# constructed by this Assemblage.
+	attr_accessor :components
+
+
+	### Add a +component_type+ to the list used when constructing a new entity from
+	### the current Assemblage. The component will be instantiated using the specified
+	### +init_args+.
+	def add( component_type, *init_args )
+		self.components[ component_type ] = init_args
+	end
+
+
+	### Construct a new entity for the specified +world+ with all of the assemblage's
+	### components.
+	def construct_for( world )
+		entity = world.create_entity
+		self.components.each do |component_type, args|
+			component = component_type.new( *args )
+			entity.add_component( component )
+		end
+
+		return entity
+	end
+
+end # module Chione::Assemblage

data/lib/chione/behaviors.rb

@@ -0,0 +1,31 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'rspec'
+require 'chione'
+
+
+RSpec.shared_examples "a Chione Component" do |args|
+
+	if args.key?( :with_fields )
+
+		args[:with_fields].each do |field|
+
+			it "declares a #{field} field" do
+				expect( described_class.fields ).to include( field.to_sym )
+			end
+
+		end
+
+	else
+
+		it "declares one or more fields" do
+			expect( described_class.fields ).to_not be_empty
+		end
+
+	end
+
+end
+
+
+

data/lib/chione/component.rb

@@ -0,0 +1,43 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'chione' unless defined?( Chione )
+
+# The Component (data) class
+class Chione::Component
+
+	# The Hash of fields implemented by the component
+	class << self
+		attr_accessor :fields
+	end
+
+
+	### Declare a field for the component named +name+, with a default value of
+	### +default+.
+	def self::field( name, default: nil )
+		self.fields ||= {}
+		self.fields[ name ] = default
+		attr_accessor( name )
+	end
+
+
+	### Create a new component with the specified +values+.
+	def initialize( values={} )
+		if self.class.fields
+			self.class.fields.each do |name, default|
+				self.method( "#{name}=" ).call( values[name] || deep_copy(default) )
+			end
+		end
+	end
+
+
+	#######
+	private
+	#######
+
+	### Make a deep copy of the specified +value+.
+	def deep_copy( value )
+		Marshal.load( Marshal.dump(value) )
+	end
+
+end # class Chione::Component

data/lib/chione/entity.rb

@@ -0,0 +1,80 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+require 'securerandom'
+
+require 'chione' unless defined?( Chione )
+
+# The Entity (identity) class
+class Chione::Entity
+	extend Loggability
+
+	# Loggability API -- send logs to the Chione logger
+	log_to :chione
+
+
+	### Return an ID for an Entity.
+	def self::make_new_id
+		return Chione.uuid.generate
+	end
+
+
+	### 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 = {}
+	end
+
+
+	######
+	public
+	######
+
+	# The Entity's ID
+	attr_reader :id
+
+	# The World the Entity belongs to
+	attr_reader :world
+
+	##
+	# The Hash of this entity's Components
+	attr_reader :components
+
+
+	### Add the specified +component+ to the entity. It will replace any existing component
+	### of the same type.
+	def add_component( component )
+		self.components[ component.class ] = component
+		self.world.add_component_for( self, component )
+	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 get_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 ]
+	end
+
+
+	### Returns +true+ if this entity has the specified +component+.
+	def has_component?( component )
+		return self.components.key?( component )
+	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,
+			self.id,
+			self.components.keys.map( &:name ).sort.join( '+' )
+		]
+	end
+
+end # class Chione::Entity

data/lib/chione/manager.rb

@@ -0,0 +1,44 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+
+require 'chione' unless defined?( Chione )
+
+
+# The Manager class
+class Chione::Manager
+	extend Loggability
+
+	# Loggability API -- send logs to the Chione logger
+	log_to :chione
+
+
+	### Create a new Chione::Manager for the specified +world+.
+	def initialize( world, * )
+		@world = world
+	end
+
+
+	######
+	public
+	######
+
+	# The World which the Manager belongs to
+	attr_reader :world
+
+
+	### Start the Manager as the world is starting. Derivatives must implement this
+	### method.
+	def start
+		raise NotImplementedError, "%p does not implement required method #start" % [ self.class ]
+	end
+
+
+	### Stop the Manager as the world is stopping. Derivatives must implement this
+	### method.
+	def stop
+		raise NotImplementedError, "%p does not implement required method #stop" % [ self.class ]
+	end
+
+end # class Chione::Manager

data/lib/chione/mixins.rb

@@ -0,0 +1,91 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'chione' unless defined?( Chione )
+
+
+module Chione
+
+	# A collection of methods for declaring other methods.
+	#
+	#   class MyClass
+	#       extend Chione::MethodUtilities
+	#
+	#       singleton_attr_accessor :types
+	#       singleton_method_alias :kinds, :types
+	#   end
+	#
+	#   MyClass.types = [ :pheno, :proto, :stereo ]
+	#   MyClass.kinds # => [:pheno, :proto, :stereo]
+	#
+	module MethodUtilities
+
+		### Creates instance variables and corresponding methods that return their
+		### values for each of the specified +symbols+ in the singleton of the
+		### declaring object (e.g., class instance variables and methods if declared
+		### in a Class).
+		def singleton_attr_reader( *symbols )
+			singleton_class.instance_exec( symbols ) do |attrs|
+				attr_reader( *attrs )
+			end
+		end
+
+		### Create instance variables and corresponding methods that return
+		### true or false values for each of the specified +symbols+ in the singleton
+		### of the declaring object.
+		def singleton_predicate_reader( *symbols )
+			singleton_class.extend( Chione::MethodUtilities )
+			singleton_class.attr_predicate( *symbols )
+		end
+
+		### Creates methods that allow assignment to the attributes of the singleton
+		### of the declaring object that correspond to the specified +symbols+.
+		def singleton_attr_writer( *symbols )
+			singleton_class.instance_exec( symbols ) do |attrs|
+				attr_writer( *attrs )
+			end
+		end
+
+		### Creates readers and writers that allow assignment to the attributes of
+		### the singleton of the declaring object that correspond to the specified
+		### +symbols+.
+		def singleton_attr_accessor( *symbols )
+			symbols.each do |sym|
+				singleton_class.__send__( :attr_accessor, sym )
+			end
+		end
+
+		### Create predicate methods and writers that allow assignment to the attributes
+		### of the singleton of the declaring object that correspond to the specified
+		### +symbols+.
+		def singleton_predicate_accessor( *symbols )
+			singleton_class.extend( Chione::MethodUtilities )
+			singleton_class.attr_predicate_accessor( *symbols )
+		end
+
+		### Creates an alias for the +original+ method named +newname+.
+		def singleton_method_alias( newname, original )
+			singleton_class.__send__( :alias_method, newname, original )
+		end
+
+
+		### Create a reader in the form of a predicate for the given +attrname+.
+		def attr_predicate( attrname )
+			attrname = attrname.to_s.chomp( '?' )
+			define_method( "#{attrname}?" ) do
+				instance_variable_get( "@#{attrname}" ) ? true : false
+			end
+		end
+
+
+		### Create a reader in the form of a predicate for the given +attrname+
+		### as well as a regular writer method.
+		def attr_predicate_accessor( attrname )
+			attrname = attrname.to_s.chomp( '?' )
+			attr_writer( attrname )
+			attr_predicate( attrname )
+		end
+
+	end # module MethodUtilities
+
+end # module Chione

data/lib/chione/system.rb

@@ -0,0 +1,69 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability'
+
+require 'chione' unless defined?( Chione )
+require 'chione/mixins'
+require 'chione/aspect'
+
+
+# The System (behavior) class
+class Chione::System
+	extend Loggability,
+	       Chione::MethodUtilities
+
+	# Loggability API -- send logs to the Chione logger
+	log_to :chione
+
+
+	### Add the specified +component_types+ to the Aspect of this System as being
+	### required in any entities it processes.
+	def self::aspect( all_of: nil, one_of: nil, none_of: nil )
+		@aspect ||= Chione::Aspect.new
+
+		@aspect = @aspect.with_all_of( all_of )   if all_of
+		@aspect = @aspect.with_one_of( one_of )   if one_of
+		@aspect = @aspect.with_none_of( none_of ) if none_of
+
+		return @aspect
+	end
+	singleton_method_alias :for_entities_that_have, :aspect
+
+
+	### Create a new Chione::System for the specified +world+.
+	def initialize( world, * )
+		@world  = world
+		@thread = nil
+	end
+
+
+	######
+	public
+	######
+
+	# The World which the System belongs to
+	attr_reader :world
+
+
+	### Start the system.
+	def start
+		self.log.info "Starting the %p" % [ self.class ]
+		@thread = Thread.new( &self.method(:process_loop) )
+	end
+
+
+	### Stop the system.
+	def stop
+		@thread.kill
+	end
+
+
+	### The main loop of the system -- process entities that this system is
+	### interested in at an appropriate interval.
+	def process_loop
+		raise NotImplementedError, "%p does not implement required method #process_loop" %
+			[ self.class ]
+	end
+
+end # class Chione::System

data/lib/chione/world.rb

@@ -0,0 +1,358 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'set'
+require 'loggability'
+require 'configurability'
+
+require 'chione' unless defined?( Chione )
+require 'chione/mixins'
+
+
+# The main ECS container
+class Chione::World
+	extend Loggability,
+	       Configurability,
+	       Chione::MethodUtilities
+
+	# Loggability API -- send logs to the Chione logger
+	log_to :chione
+
+	# Configurability API -- use the 'gameworld' section of the config
+	config_key :gameworld
+
+
+	# Default config tunables
+	CONFIG_DEFAULTS = {
+		max_stop_wait: 5,
+		timing_event_interval: 1,
+	}
+
+
+	##
+	# :singleton-method:
+	# Configurable: The maximum number of seconds to wait for any one System
+	# or Manager thread to exit before killing it when shutting down.
+	singleton_attr_accessor :max_stop_wait
+	@max_stop_wait = CONFIG_DEFAULTS[:max_stop_wait]
+
+	##
+	# :singleton-method:
+	# Configurable: The number of seconds between timing events.
+	singleton_attr_accessor :timing_event_interval
+	@timing_event_interval = CONFIG_DEFAULTS[ :timing_event_interval ]
+
+
+	### Configurability API -- configure the GameWorld.
+	def self::configure( config=nil )
+		config = self.defaults.merge( config || {} )
+
+		self.max_stop_wait = config[:max_stop_wait]
+		self.timing_event_interval = config[:timing_event_interval]
+	end
+
+
+
+
+	### Create a new Chione::World
+	def initialize
+		@entities      = {}
+		@systems       = {}
+		@managers      = {}
+
+		@subscriptions = Hash.new do |h,k|
+			h[ k ] = Set.new
+		end
+
+		@main_thread   = nil
+		@world_threads = ThreadGroup.new
+
+		@entities_by_component = Hash.new {|h,k| h[k] = Set.new }
+
+		@timing_event_count = 0
+	end
+
+
+	######
+	public
+	######
+
+	# The number of times the event loop has executed.
+	attr_reader :timing_event_count
+
+	# The Hash of all Entities in the World, keyed by ID
+	attr_reader :entities
+
+	# The Hash of all Systems currently in the World, keyed by class.
+	attr_reader :systems
+
+	# The Hash of all Managers currently in the World, keyed by class.
+	attr_reader :managers
+
+	# The ThreadGroup that contains all Threads managed by the World.
+	attr_reader :world_threads
+
+	# The Thread object running the World's IO reactor loop
+	attr_reader :io_thread
+
+	# The Hash of event subscription callbacks registered with the world, keyed by
+	# event pattern.
+	attr_reader :subscriptions
+
+
+	### Start the world; returns the Thread in which the world is running.
+	def start
+		@main_thread = Thread.new do
+			Thread.current.abort_on_exception = true
+			self.log.info "Main thread (%s) started." % [ Thread.current ]
+			@world_threads.add( Thread.current )
+			@world_threads.enclose
+
+			self.start_managers
+			self.start_systems
+
+			self.timing_loop
+		end
+
+		self.log.info "Started main World thread: %p" % [ @main_thread ]
+		return @main_thread
+	end
+
+
+	### Start any Managers registered with the world.
+	def start_managers
+		self.log.info "Starting %d Managers" % [ self.managers.length ]
+		self.managers.each do |manager_class, mgr|
+			self.log.debug "  starting %p" % [ manager_class ]
+			start = Time.now
+			mgr.start
+			finish = Time.now
+			self.log.debug "  started in %0.5fs" % [ finish - start ]
+		end
+	end
+
+
+	### Start any Systems registered with the world.
+	def start_systems
+		self.log.info "Starting %d Systems" % [ self.systems.length ]
+		self.systems.each do |system_class, sys|
+			self.log.debug "  starting %p" % [ system_class ]
+			start = Time.now
+			sys.start
+			finish = Time.now
+			self.log.debug "  started in %0.5fs" % [ finish - start ]
+		end
+	end
+
+
+	### Returns +true+ if the World has been started (but is not necessarily running yet).
+	def started?
+		return @main_thread && @main_thread.alive?
+	end
+
+
+	### Returns +true+ if the World is running (i.e., if #start has been called)
+	def running?
+		return self.started? && self.timing_event_count.nonzero?
+	end
+
+
+	### Stop the world.
+	def stop
+		self.systems.each {|_, sys| sys.stop }
+		self.managers.each {|_, mgr| mgr.stop }
+
+		self.world_threads.list.each do |thr|
+			next if thr == @main_thread
+			thr.join( self.class.max_stop_wait )
+		end
+
+		self.stop_timing_loop
+	end
+
+
+	### Halt the main timing loop. By default, this just kills the world's main thread.
+	def stop_timing_loop
+		@main_thread.kill
+	end
+
+
+	### Subscribe to events with the specified +event_name+. Returns the callback object
+	### for later unsubscribe calls.
+	def subscribe( event_name, callback=nil )
+		callback = Proc.new if !callback && block_given?
+
+		raise LocalJumpError, "no callback given" unless callback
+		raise ArgumentError, "callback is not callable" unless callback.respond_to?( :call )
+		raise ArgumentError, "callback has wrong arity" unless
+			callback.arity >= 2 || callback.arity < 0
+
+		@subscriptions[ event_name ].add( callback )
+
+		return callback
+	end
+
+
+	### Unsubscribe from events that publish to the specified +callback+.
+	def unsubscribe( callback )
+		@subscriptions.values.each {|cbset| cbset.delete(callback) }
+	end
+
+
+	### Publish an event with the specified +event_name+, calling any subscribers with
+	### the specified +payload+.
+	def publish( event_name, *payload )
+		self.log.debug "Publishing a %p event: %p" % [ event_name, payload ]
+		@subscriptions.each do |pattern, callbacks|
+			next unless File.fnmatch?( pattern, event_name, File::FNM_EXTGLOB|File::FNM_PATHNAME )
+
+			callbacks.each do |callback|
+				begin
+					callback.call( event_name, payload )
+				rescue => err
+					self.log.error "%p while calling %p for a %p event: %s" %
+						[ err.class, callback, event_name, err.message ]
+					callbacks.delete( callback )
+				end
+			end
+		end
+	end
+
+
+	### Return a new Chione::Entity for the receiving World.
+	def create_entity( assemblage=nil )
+		entity = if assemblage
+				assemblage.construct_for( self )
+			else
+				Chione::Entity.new( self )
+			end
+
+		@entities[ entity.id ] = entity
+
+		self.publish( 'entity/created', entity )
+		return entity
+	end
+
+
+	### Destroy the specified entity and remove it from any registered
+	### systems/managers.
+	def destroy_entity( entity )
+		raise ArgumentError, "%p does not contain entity %p" % [ self, entity ] unless
+			self.has_entity?( entity )
+
+		self.publish( 'entity/destroyed', entity )
+		@entities_by_component.each_value {|set| set.delete(entity) }
+		@entities.delete( entity.id )
+	end
+
+
+	### Returns +true+ if the world contains the specified +entity+ or an entity
+	### with +entity+ as the ID.
+	def has_entity?( entity )
+		if entity.respond_to?( :id )
+			return @entities.key?( entity.id )
+		else
+			return @entities.key?( entity )
+		end
+	end
+
+
+	### Register the specified +component+ as having been added to the specified
+	### +entity+.
+	def add_component_for( entity, component )
+		@entities_by_component[ component.class ].add( entity )
+	end
+
+
+	### Return 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 )
+	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
+
+		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
+	end
+
+
+	### 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
+
+		if self.running?
+			self.log.info "Starting %p added to running world." % [ system_type ]
+			system_obj.start
+		end
+
+		self.publish( 'system/added', system_type )
+		return system_obj
+	end
+
+
+	### 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
+
+		if self.running?
+			self.log.info "Starting %p added to running world." % [ manager_type ]
+			manager_obj.start
+		end
+
+		self.publish( 'manager/added', manager_type )
+		return manager_obj
+	end
+
+
+	#########
+	protected
+	#########
+
+	### The loop the main thread executes after the world is started. The default
+	### implementation just broadcasts the +timing+ event, so will likely want to
+	### override this if the main thread should do something else.
+	def timing_loop
+		self.log.info "Starting timing loop."
+		last_timing_event = Time.now
+		interval = self.class.timing_event_interval
+		@timing_event_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 )
+
+			@timing_event_count += 1
+			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 ]
+			end
+		end
+
+	ensure
+		self.log.info "Exiting timing loop."
+	end
+
+
+end # class Chione::World
+