- Made many small bugfixes to the @parent and @create functions as well as their underlying methods.

- Made it so user #1 is also affected by the on_player_creation() function.
- Added an event folder for custom events, including a working example
- Expanded the example commands and parents to include the changes to how they should be initialized.
- Added an optional ansi scheme (not active by default)

game/gamesrc/commands/example.py

@@ -1,18 +1,48 @@
 """
-This is an example command module that may be copied and used to serve as the
-basis to newly created modules. You'll need to make sure that this or any new
-modules are added to settings.py under CUSTOM_COMMAND_MODULES or
-CUSTOM_UNLOGGED_COMMAND_MODULES, which are tuples of module import path strings.
+This is an example command module for showing the pluggable command system
+in action. 
+
+You'll need to make sure that this or any new modules you create are added to
+game/settings.py under CUSTOM_COMMAND_MODULES or CUSTOM_UNLOGGED_COMMAND_MODULES,
+which are tuples of module import path strings.
 See src/config_defaults.py for more details.
+
+E.g. to add this example command for testing, your entry in game/settings.py would
+look like this:
+
+CUSTOM_COMMAND_MODULES = ('game.gamesrc.commands.example',)
+
+(note the extra comma at the end to make this into a Python tuple. It's only
+needed if you have only one entry.)
+
 """
+
 # This is the common global CommandTable object which we'll be adding the
-# example command to.
+# example command to. We can add any number of commands this way in the
+# same file.
 from src.cmdtable import GLOBAL_CMD_TABLE
 
 def cmd_example(command):
+    """    
+    This is the help text for the 'example' command, a command to
+    show how the pluggable command system works.
+
+    For testing, you can try calling this with different switches and
+    arguments, like
+       > example/test/test2 Hello
+    and see what is returned.
+
+    <<TOPIC:example_auto_help>>
+
+    This is a subtopic to the main example command help entry.
+    
+    Note that this text is auto-added since auto_help=True
+    was set in the call to add_function. Any number of subtopics like
+    this one can be added on the fly using the auto-help system. See
+    help topics on 'help' and 'help_staff' for more information and
+    options.
     """
-    An example command to show how the pluggable command system works.
-    """
+
     # By building one big string and passing it at once, we cut down on a lot
     # of emit_to() calls, which is generally a good idea.
     retval = "----- Example Command -----\n\r"
@@ -33,5 +63,32 @@ def cmd_example(command):
     # Extra variables passed with cmdtable.py's add_command().
     retval += " Extra vars: %s\n\r" % command.extra_vars
     command.source_object.emit_to(retval)
-# Add the command to the common global command table.
-GLOBAL_CMD_TABLE.add_command("example", cmd_example),
+
+# Add the command to the common global command table. Note that
+# since auto_help=True, help entries named "example" and
+# "example_auto_help" (as defined in the __doc__ string) will
+# automatically be created for us.
+GLOBAL_CMD_TABLE.add_command("example", cmd_example, auto_help=True),
+
+
+
+#another simple example
+
+def cmd_emote_smile(command):
+    """
+    Simplistic 'smile' emote. 
+    """
+    #get the source object (that is, the player using the command)
+    caller = command.source_object
+    #find name of caller
+    name = caller.get_name(show_dbref=False)
+    #get the location caller is at
+    location = caller.get_location()
+    #build the emote
+    text = "%s smiles." % name
+    #emit the emote to everyone at the current location
+    location.emit_to_contents(text)
+
+#add to global command table (no auto_help activated)
+GLOBAL_CMD_TABLE.add_command('smile', cmd_emote_smile)
+

game/gamesrc/events/example.py

@@ -0,0 +1,55 @@
+"""
+Example of the event system. To try it out, make sure to import it from somewhere
+covered by @reload (like the script parent). Create an object inheriting
+the red_button parent to see its effects (e.g. @create button=examples/red_button)
+
+Technically the event don't contain any game logics, all it does is locate all
+objects inheriting to a particular script parent and calls one of its functions
+at a regular interval.
+"""
+
+from src.events import IntervalEvent
+from src.scheduler import add_event
+from src.objects.models import Object
+
+#the logger is useful for debugging since there is no source object to send to
+from src.logger import log_infomsg
+
+#Example of the event system. This example adds an event to the red_button parent
+#in parents/examples. It makes the button blink temptingly at a regular interval.
+
+class EventBlinkButton(IntervalEvent):
+    """    
+    This event lets the button flash at regular intervals. 
+    """
+    def __init__(self):
+        """
+        A custom init method also storing the source object.
+
+        """
+        super(EventBlinkButton, self).__init__()
+        self.name = 'event_blink_red_button'
+        #how often to blink, in seconds
+        self.interval = 30 
+        #the description is seen when you run @ps in-game.
+        self.description = "Blink red buttons regularly."            
+
+    def event_function(self):
+        """
+        This stub function is automatically fired every self.interval seconds.
+
+        In this case we do a search for all objects inheriting from the correct
+        parent and call a function on them.
+        """
+        #find all objects inheriting from red_button (parents are per definition
+        #stored with the gamesrc/parent/ drawer as a base)
+        parent = 'examples.red_button'
+        buttons = Object.objects.global_object_script_parent_search(parent)
+        log_infomsg("buttons found: %s" % buttons)
+
+        for b in buttons:
+            b.scriptlink.blink()
+        
+#create and add the event to the global handler
+blink_event = EventBlinkButton()
+add_event(blink_event)

game/gamesrc/parents/base/basicobject.py

@@ -19,4 +19,4 @@ def class_factory(source_obj):
     
     source_obj: (Object) A reference to the object being scripted (the child).
     """
-    return BasicObject(source_obj)     
+    return BasicObject(source_obj)     

game/gamesrc/parents/examples/custom_basicobject.py

@@ -0,0 +1,55 @@
+"""
+Simple example of a custom modified object, derived from the base object. 
+
+If you want to make this your new default object type, move this into
+gamesrc/parents and set SCRIPT_DEFAULT_OBJECT = 'custom_basicobject'
+in game/settings.py. 
+
+Generally, if you want to conveniently set future objects to inherit from this
+script parent (not as a default), this files and others like it need to be
+located under the game/gamesrc/parent directory. 
+"""
+from game.gamesrc.parents.base.basicobject import BasicObject
+
+class CustomBasicObject(BasicObject):
+    
+    def at_object_creation(self):
+        """
+        This function is called whenever the object is created. Use
+        this instead of __init__ to set start attributes etc on a
+        particular object type.
+        """
+        
+        #Set an "sdesc" (short description) attribute on object,
+        #defaulting to its given name
+
+        #get the stored object related to this class
+        obj = self.scripted_obj 
+
+        #find out the object's name
+        name = obj.get_name(fullname=False,
+                            show_dbref=False,
+                            show_flags=False)
+        #assign the name to the new attribute
+        obj.set_attribute('sdesc',name)
+
+    def at_object_destruction(self, pobject=None):
+        """
+        This is triggered when an object is about to be destroyed via
+        @destroy ONLY. If an object is deleted via delete(), it is assumed
+        that this method is to be skipped.
+        
+        values:
+            * pobject: (Object) The object requesting the action.
+        """        
+        pass
+
+
+def class_factory(source_obj):
+    """
+    This method is called by any script you retrieve (via the scripthandler). It
+    creates an instance of the class and returns it transparently. 
+    
+    source_obj: (Object) A reference to the object being scripted (the child).
+    """
+    return CustomBasicObject(source_obj)     

game/gamesrc/parents/examples/custom_basicplayer.py

@@ -0,0 +1,67 @@
+"""
+This is an example of customizing the basic player character object.
+You will want to do this to add all sorts of custom things like
+attributes, skill values, injuries and so on. 
+
+If you want to make this the default player object for all players, move it
+into gamesrc/parents and set SCRIPT_DEFAULT_PLAYER = 'custom_basicplayer'
+in game/settings.py.
+"""
+
+from game.gamesrc.parents.base.basicplayer import BasicPlayer
+
+class CustomBasicPlayer(BasicPlayer):    
+
+    def at_player_creation(self):        
+        """
+        Called when player object is first created. Use this
+        instead of __init__ to define any custom attributes
+        all your player characters should have. 
+        """
+        
+        #Example: Adding a default sdesc (short description)
+
+        #get the stored object related to this class
+        pobject = self.scripted_obj
+        #set the attribute
+        pobject.set_attribute('sdesc', 'A normal person')
+        
+    def at_pre_login(self, session):
+        """
+        Called when the player has entered the game but has not
+        logged in yet.
+        """
+        pass
+    
+    def at_post_login(self, session):
+        """
+        This command is called after the player has logged in but
+        before he is allowed to give any commands. 
+        """
+        #get the object linked to this class
+        pobject = self.scripted_obj
+        
+        #find out more about our object
+        name = pobject.get_name(fullname=False,
+                                show_dbref=False,
+                                show_flags=False)
+        sdesc = pobject.get_attribute_value('sdesc')
+                
+        #send a greeting using our new sdesc attribute
+        pobject.emit_to("You are now logged in as %s - %s." % (name, sdesc))
+
+        #tell everyone else we're here
+        pobject.get_location().emit_to_contents("%s - %s, has connected." %
+                                                (name, sdesc), exclude=pobject)
+        #show us our surroundings                                        
+        pobject.execute_cmd("look")
+
+                            
+def class_factory(source_obj):
+    """
+    This method is called by any script you retrieve (via the scripthandler). It
+    creates an instance of the class and returns it transparently. 
+    
+    source_obj: (Object) A reference to the object being scripted (the child).
+    """    
+    return CustomBasicPlayer(source_obj)

game/gamesrc/parents/examples/red_button.py

@@ -1,35 +1,110 @@
 """
-An example script parent for a 
+An example script parent for a nice red button object. It has
+custom commands defined on itself that are only useful in relation to this
+particular object. See example.py in gamesrc/commands for more info
+on the pluggable command system. 
+
+Assuming this script remains in gamesrc/parents/examples, create an object
+of this type using @create button=examples.red_button
+
+This file also shows the use of the Event system to make the button
+send a message to the players at regular intervals. Note that if you create a
+test button you must drop it before you will see its messages!
+
 """
 from game.gamesrc.parents.base.basicobject import BasicObject
 
+#you have to import the event definition(s) from somewhere covered by @reload,
+# - this is as good a place as any. Uncomment to turn off event system.
+import game.gamesrc.events.example 
+
+#
+#commands on the button object
+#
+
 def cmd_push_button(command):
     """
-    An example command to show how the pluggable command system works.
-    """
-    # By building one big string and passing it at once, we cut down on a lot
-    # of emit_to() calls, which is generally a good idea.
-    retval = "You have pushed the button on: %s" % (command.scripted_obj.get_name())
+
+    This is a simple command that handles a user pressing the
+    button by returning a message.
+    """    
+    retval = "There is a loud bang: BOOOM!"
     command.source_object.emit_to(retval)
 
+def cmd_pull_button(command):
+    """
+    An example of a second defined command (for those who
+    don't know how a button works ... ;) )
+    """
+    retval = "A button is meant to be pushed, not pulled!"
+    command.source_object.emit_to(retval)
+                        
+#
+#The object itself
+#
+    
 class RedButton(BasicObject):
+
     def __init__(self, scripted_obj, *args, **kwargs):
         """
         This is called when class_factory() instantiates a temporary instance
         of the script parent. This is typically not something you want to
         mess with much.
         """
-        # Calling the super classes __init__ is critical! Never forget to do
+        # Calling the super class' __init__ is critical! Never forget to do
         # this or everything else from here on out will fail.
         super(RedButton, self).__init__(scripted_obj, args, kwargs)
-        # Add the command to the object's command table.
+        # Add the commands to the object's command table (this is about
+        #the only thing you should use the __init__ for).
         self.command_table.add_command("pushbutton", cmd_push_button)
+        self.command_table.add_command("pullbutton", cmd_pull_button)
+
+
+    def at_object_creation(self):
+        """
+        This function is called when object is created. Use this
+        preferably over __init__.
+
+        In this case all we do is add the commandtable
+        to the object's own command_table variable; this makes
+        the commands we've added to COMMAND_TABLE available to
+        the user whenever the object is around.
+        """
+        #get stored object related to this class
+        obj = self.scripted_obj
+        
+        obj.set_description("This is your standard big red button.")
+        obj.set_attribute("breakpoint", 10)
+        obj.set_attribute("count", 0)
+        
+    def blink(self):
+        """If the event system is active, it will regularly call this function to make
+        the button blink. Note the use of attributes to store the variable count and
+        breakpoint in a persistent way."""
+        obj = self.scripted_obj
+        
+        try:            
+            count = int(obj.get_attribute_value("count"))
+            breakpoint = int(obj.get_attribute_value("breakpoint"))        
+        except TypeError:
+            return 
+
+        if count <= breakpoint:
+            if int(count) == int(breakpoint):            
+                s = "The button flashes, then goes dark. "
+                s += "Looks like the lamp just broke."
+            else: 
+                s = "The red button flashes, demanding your attention."
+            count += 1            
+            obj.set_attribute("count",count)            
+            obj.get_location().emit_to_contents(s)
 
 def class_factory(source_obj):
     """
-    This method is called any script you retrieve (via the scripthandler). It
+    This method is called by any script you retrieve (via the scripthandler). It
     creates an instance of the class and returns it transparently. 
     
     source_obj: (Object) A reference to the object being scripted (the child).
     """
-    return RedButton(source_obj)  
+    return RedButton(source_obj)  
+