root/trunk/lib/fm/locus.rb

#!/usr/bin/ruby
# 
# This file contains the FaerieMUD::Locus class, a derivative of
# FaerieMUD::Entity. Instances of this class and its derivatives are entities
# which occupy a location, have geometry and orientation, are capable of
# colliding with each other, have relationships of containment with one another,
# have componented construction/internal location, and have their own Mana
# potential. They also introduce event propagation, which is the system which
# causes events to move from one object to another based on their relationships.
# 
# == Location
#
# Location in the world is defined by two attributes: containment and local
# coordinates.
#
# === Containment
#
# Containment is the expression of a relation of proximity or enclosure between
# one object and another. Containment affects the way events are propagated, and
# is a factor in determining an object's perceptual salience in the description
# engine.
#
# Containment at the Locus level is the simplest kind of containment; it
# expresses a relationship of purely hierarchical enclosure of one object within
# another's physical geometry. In physics terms, it means that one object's
# geometry is contained within another's transform group.
#
# Some derivatives of Locus will probably need to define additional behaviours
# and attributes to express their ideas of what containment means to them.
#
# === Local Coordinates
#
# Loci also have a relationship of location with their container, which provides
# a local coordinate system for finer-grained directed event propagation and
# description. The form the coordinate system takes is up to the specific
# implementation of the container -- it can be cartesian coordinates (in which
# case the container might also use an ODE::Space to represent its inner space),
# or a simple location list for smaller objects.
#
# === Collision
#
# When two loci try to occupy the same space, a collision results. Most of
# FaerieMUD's collision system is contained in this class. Each Locus contains a
# FaerieMUD::Physics::Geometry and a FaerieMUD::Physics::TransformGroup. The
# Geometry is the object which contains the object's location in the game world
# relative to its container. The TransformGroup aggregates groups of objects
# together so they can be transformed (ie., moved, rotated, etc.) as one
# object. Objects which are added to the contents will be added to the
# TransformGroup.
#
# ==== Componented Construction
#
# Componented construction is a behaviour which maintains a list of parts which
# make up an integral whole, each of which may be or may not be a unique object
# instance. This is used to model the detail of a component system for objects
# without having to maintain an instance of each component in the game
# world. See http://docs.faeriemud.org/bin/view/Dream/Components for more
# information.
#
# == Event Propagation
#
# Loci also are capable of propagating events to the objects which contain or
# are contained by them. This propagation is purely heirarchical in the Locus
# class itself, but may be overridden to introduce more complex propagation
# behaviours in derivatives.
#
# There are two kinds of event propagation: immersion and dispersal.
#
# === Immersion
#
# Event immersion is the propagation of events from an object to its
# contents. Objects are only affected by events during this kind of
# propagation. Immersion is controlled by an object's handlers, which must
# propagate events (or modified clones of them) further inward if it is called
# for.
#
# === Dispersal
#
# Dispersal is the propagation of events from an object to its
# container/s. Objects should not be affected by event they disperse; if an
# event is to affect an object, it must be reflected back by one of the object's
# containers. Events typically are dispersed to the widest extent they can
# affect in a given tick before being reflected back.
#
# == Subversion ID
# 
# $Id$
#
# == Authors
# 
# * Michael Granger <ged@FaerieMUD.org>
# 
# :include: LICENSE
#
#---
#
# Please see the file LICENSE for licensing details.
#

require 'monitor'

require 'fm/entity'
require 'fm/mixins'
require 'fm/exceptions'

### Object class for Entities which occupy a location, have geometry and
### orientation, are capable of colliding with each other, have relationships of
### containment with one another, and have their own Mana potential. Also
### contains the base event propagation subsystem.
class FaerieMUD::Locus < FaerieMUD::Entity
        contributors :ged

        # SVN Revision
        SVNRev = %q$Rev$

        # SVN Id
        SVNId = %q$Id$



        ### Create a new Locus object.
        def initialize( args={} )
                @containers     = []
                @contents       = []

                super
        end



        ######
        public
        ######

        # The Array of objects which contain the receiver, if any; may be empty
        # (if it is not contained by anything) or one or more FaerieMUD::Locus
        # objects.
        attr_reader :containers

        # The Array of FaerieMUD::Locus objects which are contained within the
        # receiver.
        attr_reader :contents



        #############################################################
        ###     C O N T A I N M E N T
        #############################################################
        
        ### Adds the specified objects (FaerieMUD::Locus objects) to the
        ### contents of the receiver.
        def add_contents( *objects )
                synchronize do
                        objects.each do |obj|
                                if obj.contains?( self )
                                        raise FaerieMUD::ContainmentError,
                                              "%s cannot both be contained by and contain %s" %
                                              [ obj.to_s, self.to_s ]
                                end
                                obj.add_container(self)
                        end
                        synchronize( Sync::EX ) { @contents |= objects }
                end

                return objects
        end


        ### Append operator -- add the specified ojbect to the contents of the
        ### receiver and return the receiver.
        def <<( object )
                self.add_contents( object )
                return self
        end


        ### Remove the given objects, or if a class was given, all objects of
        ### the given class or its derivatives from the contents of the
        ### receiver.
        def remove_contents( *objects )
                removedObjects = nil

                # Expand classes into the objects they match
                synchronize( Sync::SH ) do
                        expanded = objects.collect do |obj|
                                if obj.is_a?( Class )
                                        @contents.find_all {|cobj| cobj.is_a?(obj)}
                                else
                                        obj
                                end
                        end.flatten.uniq

                        # Get the objects that'll be removed by intersecting the expanded
                        # list with the current contents; then remove 'em.
                        removedObjects = @contents & expanded
                        removedObjects.each {|obj| obj.remove_container(self) }
                        synchronize( Sync::EX ) { @contents -= removedObjects }
                end

                return removedObjects
        end


        ### Add the specified object to the list of the receiver's containers.
        def add_container( object )
                synchronize( Sync::SH ) {
                        if self.contains?( object )
                                raise FaerieMUD::ContainmentError,
                                        "receiver is %s's container" % object.to_s
                        end

                        synchronize( Sync::EX ) {
                                @containers |= [object]
                        }
                }
        end


        ### Remove the specified +object+ from the list of the receiver's
        ### containers.
        def remove_container( object )
                synchronize( Sync::EX ) { @containers -= [object] }
        end


        ### Return +true+ if the receiver contains the specified object.
        def contains?( obj )
                return (@contents.include?( obj ) || @contents.find {|l| l.contains?(obj) }) ?
                        true :
                        false
        end
        alias_method :include?, :contains?


        ### Return +true+ if the receiver is contained by the specified object.
        def contained_by?( obj )
                return @containers.include?( obj )
        end


        #############################################################
        ###     E V E N T S
        #############################################################

        ### The fallback handler for Loci just immerses any events it receives.
        def handle_any_event( event )
                self.log.debug( "Fallback handler: Immersing a #{event.class.name}" )
                self.immerse_events( event )
        end


        ### Event dispersal: propagate events outward (to the receiver's
        ### container/s).
        def disperse_events( *events )
                results = []

                # Pass on all of the given events to each of this object's
                # containers.
                @containers.each do |obj|
                        results << obj.disperse_events( *events )
                end

                return results.flatten
        end



        #########
        protected
        #########

        ### Event immersion: propagate events inward (to the receiver's
        ### contents).
        def immerse_events( *events )
                self.log.debug "Immersing %d event" % [events.length]
                results = []

                # Distribute all the events to each contained item, saving any
                # resulting events for return.
                @contents.each do |obj|
                        results << obj.handle_events( *events )
                end

                return results.flatten
        end



end # class FaerieMUD::Locus