root/trunk/lib/fm/spirit.rb

#!/usr/bin/ruby
# 
# This file contains the FaerieMUD::Spirit class. Instances of this class are
# the permanent record of a player's accomplishments in the world, and also the
# means by which she controls characters or other AnimatedObjects in the world.
# 
# == Subversion ID
# 
# $Id$
# 
# == Authors
# 
# * Michael Granger <ged@FaerieMUD.org>
# 
# :include: LICENSE
#
#---
#
# Please see the file LICENSE for licensing details.
#

require 'fm/mixins'
require 'fm/exceptions'
require 'fm/commandparser'
require 'fm/statistic'

### Object class for maintaining a permanent record of a player's
### accomplishments in the world. Also the means by which she controls
### FaerieMUD::Character objects or other instances of FaerieMUD::AnimatedObject
### in the world.
class FaerieMUD::Spirit < FaerieMUD::Entity
        include FaerieMUD::AccessorFunctions
        
        contributors :ged

        # SVN Revision
        SVNRev = %q$Rev$

        # SVN Id
        SVNId = %q$Id$



        #################################################################
        ###     C O N S T I T U E N T   C L A S S E S
        #################################################################

        ### The spirit's interface to the currently-animated object's physical
        ### constituent.
        class PhysicalAspect < FaerieMUD::Entity
                include FaerieMUD::ComposedObject::Constituent
                contributors :ged
                def_statistic :incarnativity, :presence
        end


        ### The spirit's interface to the currently-animated object's mental
        ### constituent.
        class MentalAspect < FaerieMUD::Entity
                include FaerieMUD::ComposedObject::Constituent
                contributors :ged
                def_statistic :kenning, :cognizance
        end

        
        ### The spirit's interface to the currently-animated object's creative
        ### constituent.
        class CreativeAspect < FaerieMUD::Entity
                include FaerieMUD::ComposedObject::Constituent
                contributors :ged
                def_statistic :divinity, :influence
        end


        ### Define accessor methods for the given aspect.
        def self::def_aspect_methods( *aspects )
                aspects.each do |aspect|
                        aspectClass = const_get( "#{aspect.to_s.capitalize}Aspect" ) or
                                raise FaerieMUD::ConstituentError,
                                "Cannot define aspect methods for non-existent aspect '#{aspect}'"

                        # The aspect itself
                        define_method( aspect ) { @aspects[aspect] }
                        define_method( "#{aspect}=" ) {|arg|
                                check_type( arg, aspectClass )
                                @aspects[aspect] = arg
                        }

                        # Statistic accessors
                        develAspect, linearAspect = aspectClass.statistic_names
                        develAspectEq = "#{develAspect}=".intern
                        linearAspectEq = "#{linearAspect}=".intern

                        self.log.debug "Defining statistic accessors: %s/%s" %
                                [ develAspect, linearAspect ]

                        define_method( develAspect ) {
                                self.send(aspect).statistic.developmental
                        }
                        define_method( develAspectEq ) {|arg|
                                self.send(aspect).statistic.developmental = arg
                        }
                        define_method( linearAspect ) {
                                self.send(aspect).statistic.linear
                        }
                        define_method( linearAspectEq ) {|arg|
                                self.send(aspect).statistic.linear = arg
                        }
                end
        end
        

        #################################################################
        ###     I N S T A N C E   M E T H O D S
        #################################################################

        ### Create a new FaerieMUD::Spirit object.
        def initialize( args={} )
                @animated_object = nil
                @parser = FaerieMUD::CommandParser::new

                @io_handlers = {
                        :input          => nil,
                        :output         => nil,
                }

                @aspects = {
                        :physical => PhysicalAspect::new,
                        :mental => MentalAspect::new,
                        :creative => CreativeAspect::new,
                }

                @input_thread = nil

                super
        end


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

        # The Spirit's FaerieMUD::CommandParser object.
        attr_locked_reader :parser

        # The AnimatedObject controlled by this Spirit.
        attr_locked_reader :animated_object

        # IO Callbacks
        attr_reader :io_handlers

        # Pseudo-ComposedObject accessors
        def_aspect_methods :physical, :mental, :creative

        # The input thread
        attr_reader :input_thread

        
        ### Provide a +handler+ for output events.
        def on_output( &handler )
                @io_handlers[:output] = handler
        end


        ### Provide a +callback+ which will be called when the spirit is ready for
        ### input.
        def on_input_ready( &handler )
                @io_handlers[:input] = handler
        end


        ### Add the specified +object+ (FaerieMUD::AnimatedObject) to the list
        ### being controlled by the Spirit.
        def animate( object )
                self.writelocked do
                        object.controller = self
                        @animated_object = object
                        self.update_parser
                end
        end


        ### Remove the specified +object+ (FaerieMUD::AnimatedObject) from the
        ### list being controlled by the Spirit.
        def deanimate
                return if @animated_object.nil?

                self.writelocked do
                        @animated_object.controller = nil
                        @animated_object = nil
                end
        end
        alias_method :unanimate, :deanimate

        
        ### Synchronize the parser's verbset with the set of verbs from the
        ### currently-animated objects.
        def update_parser
                verbs = @animated_object.verbs
                @parser.update_verb_set( *verbs )
        end


        ### Output the given +message+ to the player controlling the Spirit.
        def output( message )
                @io_handlers[:output].call( message )
        end


        ### Start the input loop of the spirit to fetch user input.
        def start
                self.log.debug "Starting input thread"
                @input_thread = Thread::new( &(method(:input_loop)) )
                self.log.debug "Input thread started: %p" % [@input_thread]
        end


        ### Returns +true+ if the Spirit's input thread is running
        def running?
                @input_thread.alive? && @input_thread[:running]
        end



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

        ### Wait for input from the Player and pass it to the CommandParser for
        ### action.
        def input_loop
                self.log.debug "  in input loop on %p" % [self]
                Thread.current.abort_on_exception = true

                Thread.current[:running] = true
                while Thread.current[:running]
                        self.log.debug "  calling input iohandler"
                        rawInput = @io_handlers[:input].call or next

                        self.log.debug "  Got input %p" % [rawInput]
                        @parser.parse( rawInput )
                end
        end

end # class FaerieMUD::Spirit