Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated objects.objects docs

Browse source
This commit is contained in:
Griatch 2015-03-09 12:44:28 +01:00
parent 60163184ad
commit 733f1c6147
1 changed files with 392 additions and 218 deletions
Download patch file Download diff file Expand all files Collapse all files

600
evennia/objects/objects.py
View file

@ -169,14 +169,18 @@ class DefaultObject(ObjectDB):
@property @property
def has_player(self): def has_player(self):
""" """
Convenience function for checking if an active player is Convenience property for checking if an active player is
currently connected to this object currently connected to this object.
""" """
return any(self.sessions) return any(self.sessions)
@property @property
def is_superuser(self): def is_superuser(self):
"Check if user has a player, and if so, if it is a superuser." """
Check if user has a player, and if so, if it is a superuser.
"""
return self.db_player and self.db_player.is_superuser \ return self.db_player and self.db_player.is_superuser \
and not self.db_player.attributes.get("_quell") and not self.db_player.attributes.get("_quell")
@ -186,7 +190,16 @@ class DefaultObject(ObjectDB):
objects that has this object set as its location. objects that has this object set as its location.
This should be publically available. This should be publically available.
exclude is one or more objects to not return Args:
exclude (Object): Object to exclude from returned
contents list
Returns:
contents (list): List of contents of this Object.
Notes:
Also available as the `contents` property.
""" """
return self.contents_cache.get(exclude=exclude) return self.contents_cache.get(exclude=exclude)
contents = property(contents_get) contents = property(contents_get)
@ -195,8 +208,8 @@ class DefaultObject(ObjectDB):
@property @property
def exits(self): def exits(self):
""" """
Returns all exits from this object, i.e. all objects Returns all exits from this object, i.e. all objects at this
at this location having the property destination != None. location having the property destination != `None`.
""" """
return [exi for exi in self.contents if exi.destination] return [exi for exi in self.contents if exi.destination]
@ -328,25 +341,25 @@ class DefaultObject(ObjectDB):
""" """
Simple shortcut wrapper to search for players, not characters. Simple shortcut wrapper to search for players, not characters.
searchdata - search criterion - the key or dbref of the player Args:
searchdata (str): Search criterion - the key or dbref of the player
to search for. If this is "here" or "me", search to search for. If this is "here" or "me", search
for the player connected to this object. for the player connected to this object.
quiet - return the results as a list rather than echo eventual quiet (bool): Returns the results as a list rather than
standard error messages. echo eventual standard error messages. Default `False`.
Returns: Returns:
quiet=False (default): result (Player, None or list): Just what is returned depends on
no match or multimatch: the `quiet` setting:
auto-echoes errors to self.msg, then returns None - `quiet=True`: No match or multumatch auto-echoes errors
(results are handled by settings.SEARCH_AT_RESULT to self.msg, then returns `None`. The esults are passed
and settings.SEARCH_AT_MULTIMATCH_INPUT) through `settings.SEARCH_AT_RESULT` and
match: `settings.SEARCH_AT_MULTIMATCH_INPUT`. If there is a
a unique player match unique match, this will be returned.
quiet=True: - `quiet=True`: No automatic error messaging is done, and
no match or multimatch: what is returned is always a list with 0, 1 or more
returns None or list of multi-matches matching Players.
match:
a unique object match
""" """
if isinstance(searchdata, basestring): if isinstance(searchdata, basestring):
# searchdata is a string; wrap some common self-references # searchdata is a string; wrap some common self-references
@ -361,28 +374,33 @@ class DefaultObject(ObjectDB):
def execute_cmd(self, raw_string, sessid=None, **kwargs): def execute_cmd(self, raw_string, sessid=None, **kwargs):
""" """
Do something as this object. This method is a copy of the execute_ Do something as this object. This method is a copy of the
cmd method on the session. This is never called normally, it's only `execute_cmd` method on the session. This is never called
used when wanting specifically to let an object be the caller of a normally, it's only used when wanting specifically to let an
command. It makes use of nicks of eventual connected players as well. object be the caller of a command. It makes use of nicks of
eventual connected players as well.
Argument: Args:
raw_string (string) - raw command input raw_string (string): Raw command input
sessid (int) - optional session id to return results to sessid (int, optional): Session id to return results to
**kwargs - other keyword arguments will be added to the found command
Kwargs:
Other keyword arguments will be added to the found command
object instace as variables before it executes. This is object instace as variables before it executes. This is
unused by default Evennia but may be used to set flags and unused by default Evennia but may be used to set flags and
change operating paramaters for commands at run-time. change operating paramaters for commands at run-time.
Returns Deferred - this is an asynchronous Twisted object that will Returns:
not fire until the command has actually finished executing. To defer (Deferred): This is an asynchronous Twisted object that
overload this one needs to attach callback functions to it, with will not fire until the command has actually finished
addCallback(function). This function will be called with an executing. To overload this one needs to attach
eventual return value from the command execution. callback functions to it, with addCallback(function).
This function will be called with an eventual return
This return is not used at all by Evennia by default, but might value from the command execution. This return is not
be useful for coders intending to implement some sort of nested used at all by Evennia by default, but might be useful
for coders intending to implement some sort of nested
command structure. command structure.
""" """
# nick replacement - we require full-word matching. # nick replacement - we require full-word matching.
# do text encoding conversion # do text encoding conversion
@ -437,10 +455,19 @@ class DefaultObject(ObjectDB):
def msg_contents(self, message, exclude=None, from_obj=None, **kwargs): def msg_contents(self, message, exclude=None, from_obj=None, **kwargs):
""" """
Emits something to all objects inside an object. Emits a message to all objects inside this object.
exclude is a list of objects not to send to. See self.msg() for Args:
message (str): Message to send.
exclude (list, optional): A list of objects not to send to.
from_obj (Object, optional): An object designated as the
"sender" of the message. See `DefaultObject.msg()` for
more info. more info.
Kwargs:
Keyword arguments will be passed on to `obj.msg()` for all
messaged objects.
""" """
contents = self.contents contents = self.contents
if exclude: if exclude:
@ -454,13 +481,6 @@ class DefaultObject(ObjectDB):
""" """
Moves this object to a new location. Moves this object to a new location.
Moves this object to a new location. Note that if <destination> is an
exit object (i.e. it has "destination"!=None), the move_to will
happen to this destination and -not- into the exit object itself, unless
use_destination=False. Note that no lock checks are done by this
function, such things are assumed to have been handled before calling
move_to.
Args: Args:
destination (Object): Reference to the object to move to. This destination (Object): Reference to the object to move to. This
can also be an exit object, in which case the can also be an exit object, in which case the
@ -481,8 +501,24 @@ class DefaultObject(ObjectDB):
result (bool): True/False depending on if there were problems with the move. result (bool): True/False depending on if there were problems with the move.
This method may also return various error messages to the This method may also return various error messages to the
emit_to_obj. emit_to_obj.
Notes:
No access checks are done in this method, these should be handled before
calling `move_to`.
The `DefaultObject` hooks called (if `move_hooks=True`) are, in order:
1. `self.at_before_move(destination)` (if this returns False, move is aborted)
1. `source_location.at_object_leave(self, destination)`
1. `self.announce_move_from(destination)`
1. (move happens here)
1. `self.announce_move_to(source_location)`
1. `destination.at_object_receive(self, source_location)`
1. `self.at_after_move(source_location)`
""" """
def logerr(string=""): def logerr(string=""):
"Simple log helper method"
trc = traceback.format_exc() trc = traceback.format_exc()
errstring = "%s%s" % (trc, string) errstring = "%s%s" % (trc, string)
log_trace() log_trace()
@ -600,8 +636,8 @@ class DefaultObject(ObjectDB):
def clear_contents(self): def clear_contents(self):
""" """
Moves all objects (players/things) to their home Moves all objects (players/things) to their home location or
location or to default home. to default home.
""" """
# Gather up everything that thinks this is its location. # Gather up everything that thinks this is its location.
default_home_id = int(settings.DEFAULT_HOME.lstrip("#")) default_home_id = int(settings.DEFAULT_HOME.lstrip("#"))
@ -645,14 +681,17 @@ class DefaultObject(ObjectDB):
def copy(self, new_key=None): def copy(self, new_key=None):
""" """
Makes an identical copy of this object. If you want to customize the Makes an identical copy of this object, identical except for a
copy by changing some settings, use ObjectDB.object.copy_object() new dbref in the database. If you want to customize the copy
by changing some settings, use ObjectDB.object.copy_object()
directly. directly.
new_key (string) - new key/name of copied object. If new_key is not Args:
specified, the copy will be named <old_key>_copy new_key (string): New key/name of copied object. If new_key is not
by default. specified, the copy will be named <old_key>_copy by default.
Returns: Object (copy of this one) Returns:
copy (Object): A copy of this object.
""" """
def find_clone_key(): def find_clone_key():
""" """
@ -674,10 +713,14 @@ class DefaultObject(ObjectDB):
delete_iter = 0 delete_iter = 0
def delete(self): def delete(self):
""" """
Deletes this object. Deletes this object. Before deletion, this method makes sure
Before deletion, this method makes sure to move all contained to move all contained objects to their respective home
objects to their respective home locations, as well as clean locations, as well as clean up all exits to/from the object.
up all exits to/from the object.
Returns:
noerror (bool): Returns whether or not the delete completed
successfully or not.
""" """
global _ScriptDB global _ScriptDB
if not _ScriptDB: if not _ScriptDB:
@ -727,10 +770,12 @@ class DefaultObject(ObjectDB):
def __eq__(self, other): def __eq__(self, other):
""" """
Checks for equality against an id string or another object or user. Checks for equality against an id string or another object or
user.
Args:
other (Object): object to compare to.
This has be located at this level, having it in the
parent doesn't work.
""" """
try: try:
return self.dbid == other.dbid return self.dbid == other.dbid
@ -741,6 +786,10 @@ class DefaultObject(ObjectDB):
except AttributeError: except AttributeError:
return False return False
#
# Hook methods
#
def at_first_save(self): def at_first_save(self):
""" """
This is called by the typeclass system whenever an instance of This is called by the typeclass system whenever an instance of
@ -748,6 +797,7 @@ class DefaultObject(ObjectDB):
for calling the startup hooks for the various game entities. for calling the startup hooks for the various game entities.
When overloading you generally don't overload this but When overloading you generally don't overload this but
overload the hooks called by this method. overload the hooks called by this method.
""" """
self.basetype_setup() self.basetype_setup()
self.at_object_creation() self.at_object_creation()
@ -804,11 +854,12 @@ class DefaultObject(ObjectDB):
def basetype_setup(self): def basetype_setup(self):
""" """
This sets up the default properties of an Object, This sets up the default properties of an Object, just before
just before the more general at_object_creation. the more general at_object_creation.
You normally don't need to change this unless you change some You normally don't need to change this unless you change some
fundamental things like names of permission groups. fundamental things like names of permission groups.
""" """
# the default security setup fallback for a generic # the default security setup fallback for a generic
# object. Overload in child for a custom setup. Also creation # object. Overload in child for a custom setup. Also creation
@ -834,21 +885,24 @@ class DefaultObject(ObjectDB):
setup after the object is created. An example of this is setup after the object is created. An example of this is
EXITs, who need to know keys, aliases, locks etc to set up EXITs, who need to know keys, aliases, locks etc to set up
their exit-cmdsets. their exit-cmdsets.
""" """
pass pass
def at_object_creation(self): def at_object_creation(self):
""" """
Called once, when this object is first created. This is Called once, when this object is first created. This is the
the normal hook to overload for most object types. normal hook to overload for most object types.
""" """
pass pass
def at_object_delete(self): def at_object_delete(self):
""" """
Called just before the database object is Called just before the database object is permanently
permanently delete()d from the database. If delete()d from the database. If this method returns False,
this method returns False, deletion is aborted. deletion is aborted.
""" """
return True return True
@ -859,6 +913,7 @@ class DefaultObject(ObjectDB):
happens on-demand first time the object is used or activated happens on-demand first time the object is used or activated
in some way after being created but also after each server in some way after being created but also after each server
restart or reload. restart or reload.
""" """
pass pass
@ -868,44 +923,53 @@ class DefaultObject(ObjectDB):
command handler. If changes need to be done on the fly to the command handler. If changes need to be done on the fly to the
cmdset before passing them on to the cmdhandler, this is the cmdset before passing them on to the cmdhandler, this is the
place to do it. This is called also if the object currently place to do it. This is called also if the object currently
have no cmdsets. **kwargs are usually not set but could be have no cmdsets.
used e.g. to force rebuilding of a dynamically created cmdset
or similar. Kwargs:
Usually not set but could be used e.g. to force rebuilding
of a dynamically created cmdset or similar.
""" """
pass pass
def at_pre_puppet(self, player, sessid=None): def at_pre_puppet(self, player, sessid=None):
""" """
Called just before a Player connects to this object Called just before a Player connects to this object to puppet
to puppet it. it.
player - connecting player object Args:
sessid - session id controlling the connection player (Player): This is the connecting player.
sessid (int): Session id controlling the connection.
""" """
pass pass
def at_post_puppet(self): def at_post_puppet(self):
""" """
Called just after puppeting has been completed and Called just after puppeting has been completed and all
all Player<->Object links have been established. Player<->Object links have been established.
""" """
self.player.db._last_puppet = self self.player.db._last_puppet = self
def at_pre_unpuppet(self): def at_pre_unpuppet(self):
""" """
Called just before beginning to un-connect a puppeting Called just before beginning to un-connect a puppeting from
from this Player. this Player.
""" """
pass pass
def at_post_unpuppet(self, player, sessid=None): def at_post_unpuppet(self, player, sessid=None):
""" """
Called just after the Player successfully disconnected Called just after the Player successfully disconnected from
from this object, severing all connections. this object, severing all connections.
Args:
player (Player): The player object that just disconnected
from this object.
sessid (int): Session id controlling the connection that
just disconnected.
player - the player object that just disconnected from
this object.
sessid - session id controlling the connection
""" """
pass pass
@ -914,6 +978,7 @@ class DefaultObject(ObjectDB):
This hook is called whenever the server is shutting down for This hook is called whenever the server is shutting down for
restart/reboot. If you want to, for example, save non-persistent restart/reboot. If you want to, for example, save non-persistent
properties across a restart, this is the place to do it. properties across a restart, this is the place to do it.
""" """
pass pass
@ -921,6 +986,7 @@ class DefaultObject(ObjectDB):
""" """
This hook is called whenever the server is shutting down fully This hook is called whenever the server is shutting down fully
(i.e. not for a restart). (i.e. not for a restart).
""" """
pass pass
@ -931,6 +997,17 @@ class DefaultObject(ObjectDB):
not affect the result of the lock check. It can be used e.g. to not affect the result of the lock check. It can be used e.g. to
customize error messages in a central location or other effects customize error messages in a central location or other effects
based on the access result. based on the access result.
Args:
result (bool): The outcome of the access call.
accessing_obj (Object or Player): The entity trying to
gain access. access_type (str): The type of access that
was requested.
Kwargs:
Not used by default, added for possible expandability in a
game.
""" """
pass pass
@ -939,13 +1016,19 @@ class DefaultObject(ObjectDB):
def at_before_move(self, destination): def at_before_move(self, destination):
""" """
Called just before starting to move Called just before starting to move this object to
this object to destination. destination.
destination - the object we are moving to Args:
destination (Object): The object we are moving to
Returns:
shouldmove (bool): If we should move or not.
Notes:
If this method returns False/None, the move is cancelled
before it is even started.
If this method returns False/None, the move
is cancelled before it is even started.
""" """
#return has_perm(self, destination, "can_move") #return has_perm(self, destination, "can_move")
return True return True
@ -956,7 +1039,9 @@ class DefaultObject(ObjectDB):
called while we are still standing in the old called while we are still standing in the old
location. location.
destination - the place we are going to. Args:
destination (Object): The place we are going to.
""" """
if not self.location: if not self.location:
return return
@ -969,10 +1054,12 @@ class DefaultObject(ObjectDB):
def announce_move_to(self, source_location): def announce_move_to(self, source_location):
""" """
Called after the move if the move was not quiet. At this Called after the move if the move was not quiet. At this point
point we are standing in the new location. we are standing in the new location.
Args:
source_location (Object): The place we came from
source_location - the place we came from
""" """
name = self.name name = self.name
@ -992,10 +1079,13 @@ class DefaultObject(ObjectDB):
def at_after_move(self, source_location): def at_after_move(self, source_location):
""" """
Called after move has completed, regardless of quiet mode or not. Called after move has completed, regardless of quiet mode or
Allows changes to the object due to the location it is now in. not. Allows changes to the object due to the location it is
now in.
Args:
source_location (Object): Wwhere we came from. This may be `None`.
source_location - where we came from. This may be None.
""" """
pass pass
@ -1003,8 +1093,10 @@ class DefaultObject(ObjectDB):
""" """
Called just before an object leaves from inside this object Called just before an object leaves from inside this object
moved_obj - the object leaving Args:
target_location - where the object is going. moved_obj (Object): The object leaving
target_location (Object): Where `moved_obj` is going.
""" """
pass pass
@ -1012,93 +1104,140 @@ class DefaultObject(ObjectDB):
""" """
Called after an object has been moved into this object. Called after an object has been moved into this object.
moved_obj - the object moved into this one Args:
source_location - where moved_object came from. moved_obj (Object): The object moved into this one
source_location (Object): Where `moved_object` came from.
""" """
pass pass
def at_before_traverse(self, traversing_object): def at_before_traverse(self, traversing_object):
""" """
Called just before an object uses this object to Called just before an object uses this object to traverse to
traverse to another object (i.e. this object is a type of Exit) another object (i.e. this object is a type of Exit)
Args:
traversing_object (Object): The object traversing us.
Notes:
The target destination should normally be available as
`self.destination`.
The target location should normally be available as self.destination.
""" """
pass pass
def at_traverse(self, traversing_object, target_location): def at_traverse(self, traversing_object, target_location):
""" """
This hook is responsible for handling the actual traversal, normally This hook is responsible for handling the actual traversal,
by calling traversing_object.move_to(target_location). It is normally normally by calling
only implemented by Exit objects. If it returns False (usually because `traversing_object.move_to(target_location)`. It is normally
move_to returned False), at_after_traverse below should not be called only implemented by Exit objects. If it returns False (usually
and instead at_failed_traverse should be called. because move_to returned False), at_after_traverse below
should not be called and instead at_failed_traverse should be
called.
Args:
traversing_object (Object): Object traversing us.
target_location (Object): Where target is going.
""" """
pass pass
def at_after_traverse(self, traversing_object, source_location): def at_after_traverse(self, traversing_object, source_location):
""" """
Called just after an object successfully used this object to Called just after an object successfully used this object to
traverse to another object (i.e. this object is a type of Exit) traverse to another object (i.e. this object is a type of
Exit)
The target location should normally be available as self.destination. Args:
traversing_object (Object): The object traversing us.
source_location (Object): Where `traversing_object` came from.
Notes:
The target location should normally be available as `self.destination`.
""" """
pass pass
def at_failed_traverse(self, traversing_object): def at_failed_traverse(self, traversing_object):
""" """
This is called if an object fails to traverse this object for some This is called if an object fails to traverse this object for
reason. It will not be called if the attribute err_traverse is defined, some reason.
that attribute will then be echoed back instead.
Args:
traversing_object (Object): The object that failed traversing us.
Notes:
Using the default exits, this hook will not be called if an
Attribute `err_traverse` is defined - this will in that case be
read for an error string instead.
""" """
pass pass
def at_msg_receive(self, text=None, **kwargs): def at_msg_receive(self, text=None, **kwargs):
""" """
This hook is called whenever someone This hook is called whenever someone sends a message to this
sends a message to this object. object using the `msg` method.
Note that from_obj may be None if the sender did Note that from_obj may be None if the sender did not include
not include itself as an argument to the obj.msg() itself as an argument to the obj.msg() call - so you have to
call - so you have to check for this. . check for this. .
Consider this a pre-processing method before msg is passed on
to the user sesssion. If this method returns False, the msg
will not be passed on.
Args:
text (str, optional): The message received.
Kwargs:
This includes any keywords sent to the `msg` method.
Returns:
receive (bool): If this message should be received.
Notes:
If this method returns False, the `msg` operation
will abort without sending the message.
Consider this a pre-processing method before
msg is passed on to the user sesssion. If this
method returns False, the msg will not be
passed on.
Input:
msg = the message received
from_obj = the one sending the message
Output:
boolean True/False
""" """
return True return True
def at_msg_send(self, text=None, to_obj=None, **kwargs): def at_msg_send(self, text=None, to_obj=None, **kwargs):
""" """
This is a hook that is called when /this/ object This is a hook that is called when *this* object sends a
sends a message to another object with obj.msg() message to another object with `obj.msg(text, to_obj=obj)`.
while also specifying that it is the one sending.
Args:
text (str): Text to send.
to_obj (Object): The object to send to.
Kwargs:
Keywords passed from msg()
Notes:
Since this method is executed `from_obj`, if no `from_obj`
was passed to `DefaultCharacter.msg` this hook will never
get called.
Note that this method is executed on the object
passed along with the msg() function (i.e. using
obj.msg(msg, from_obj=caller) will then launch caller.at_msg())
and if no object was passed, it will never be called.
""" """
pass pass
# hooks called by the default cmdset. # hooks called by the default cmdset.
def return_appearance(self, pobject): def return_appearance(self, looker):
""" """
This is a convenient hook for a 'look' This formats a description. It is the hook a 'look' command
command to call. should call.
Args:
looker (Object): Object doing the looking.
""" """
if not pobject: if not looker:
return return
# get and identify all objects # get and identify all objects
visible = (con for con in self.contents if con != pobject and visible = (con for con in self.contents if con != looker and
con.access(pobject, "view")) con.access(looker, "view"))
exits, users, things = [], [], [] exits, users, things = [], [], []
for con in visible: for con in visible:
key = con.key key = con.key
@ -1121,39 +1260,58 @@ class DefaultObject(ObjectDB):
def at_desc(self, looker=None): def at_desc(self, looker=None):
""" """
This is called whenever someone looks This is called whenever someone looks at this object.
at this object. Looker is the looking
object. looker (Object): The object requesting the description.
""" """
pass pass
def at_get(self, getter): def at_get(self, getter):
""" """
Called when this object has been picked up. Obs- Called by the default `get` command when this object has been
this method cannot stop the pickup - use permissions picked up.
for that!
Args:
getter (Object): The object getting this object.
Notes:
This hook cannot stop the pickup from happening. Use
permissions for that.
getter - the object getting this object.
""" """
pass pass
def at_drop(self, dropper): def at_drop(self, dropper):
""" """
Called when this object has been dropped. Called by the default `drop` command when this object has been
dropped.
Args:
dropper (Object): The object which just dropped this object.
Notes:
This hook cannot stop the pickup from happening. Use
permissions from that.
dropper - the object which just dropped this object.
""" """
pass pass
def at_say(self, speaker, message): def at_say(self, speaker, message):
""" """
Called on this object if an object inside this object speaks. Called on this object if an object inside this object speaks.
The string returned from this method is the final form The string returned from this method is the final form of the
of the speech. Obs - you don't have to add things like speech.
'you say: ' or similar, that is handled by the say command.
Args:
speaker (Object): The object speaking.
message (str): The words spoken.
Notes:
You should not need to add things like 'you say: ' or
similar here, that should be handled by the say command before
this.
speaker - the object speaking
message - the words spoken.
""" """
return message return message
@ -1164,18 +1322,19 @@ class DefaultObject(ObjectDB):
class DefaultCharacter(DefaultObject): class DefaultCharacter(DefaultObject):
""" """
This is just like the Object except it implements its own This implements an Object puppeted by a Session and what that
version of the at_object_creation to set up the script means.
that adds the default cmdset to the object.
""" """
def basetype_setup(self): def basetype_setup(self):
""" """
Setup character-specific security Setup character-specific security.
You should normally not need to overload this, but if you do, make You should normally not need to overload this, but if you do,
sure to reproduce at least the two last commands in this method (unless make sure to reproduce at least the two last commands in this
you want to fundamentally change how a Character object works). method (unless you want to fundamentally change how a
Character object works).
""" """
super(DefaultCharacter, self).basetype_setup() super(DefaultCharacter, self).basetype_setup()
@ -1184,23 +1343,22 @@ class DefaultCharacter(DefaultObject):
# add the default cmdset # add the default cmdset
self.cmdset.add_default(settings.CMDSET_CHARACTER, permanent=True) self.cmdset.add_default(settings.CMDSET_CHARACTER, permanent=True)
def at_object_creation(self):
"""
All this does (for now) is to add the default cmdset. Since
the script is permanently stored to this object (the permanent
keyword creates a script to do this), we should never need to
do this again for as long as this object exists.
"""
pass
def at_after_move(self, source_location): def at_after_move(self, source_location):
"Default is to look around after a move." """
We make sure to look around after a move.
"""
self.execute_cmd('look') self.execute_cmd('look')
def at_pre_puppet(self, player, sessid=None): def at_pre_puppet(self, player, sessid=None):
""" """
This recovers the character again after having been "stoved away" This implementation recovers the character again after having been "stoved
at the unpuppet away" to the `None` location in `at_post_unpuppet`.
Args:
player (Player): This is the connecting player.
sessid (int): Session id controlling the connection.
""" """
if self.db.prelogout_location: if self.db.prelogout_location:
# try to recover # try to recover
@ -1217,7 +1375,9 @@ class DefaultCharacter(DefaultObject):
def at_post_puppet(self): def at_post_puppet(self):
""" """
Called just after puppeting has completed. Called just after puppeting has been completed and all
Player<->Object links have been established.
""" """
self.msg("\nYou become {c%s{n.\n" % self.name) self.msg("\nYou become {c%s{n.\n" % self.name)
self.execute_cmd("look") self.execute_cmd("look")
@ -1227,8 +1387,14 @@ class DefaultCharacter(DefaultObject):
def at_post_unpuppet(self, player, sessid=None): def at_post_unpuppet(self, player, sessid=None):
""" """
We stove away the character when the player goes ooc/logs off, We stove away the character when the player goes ooc/logs off,
otherwise the character object will remain in the room also after the otherwise the character object will remain in the room also
player logged off ("headless", so to say). after the player logged off ("headless", so to say).
Args:
player (Player): The player object that just disconnected
from this object.
sessid (int): Session id controlling the connection that
just disconnected.
""" """
if self.location: # have to check, in case of multiple connections closing if self.location: # have to check, in case of multiple connections closing
self.location.msg_contents("%s has left the game." % self.name, exclude=[self]) self.location.msg_contents("%s has left the game." % self.name, exclude=[self])
@ -1242,12 +1408,13 @@ class DefaultCharacter(DefaultObject):
class DefaultRoom(DefaultObject): class DefaultRoom(DefaultObject):
""" """
This is the base room object. It's just like any Object except its This is the base room object. It's just like any Object except its
location is None. location is always `None`.
""" """
def basetype_setup(self): def basetype_setup(self):
""" """
Simple setup, shown as an example Simple room setup setting locks to make sure the room
(since default is None anyway) cannot be picked up.
""" """
super(DefaultRoom, self).basetype_setup() super(DefaultRoom, self).basetype_setup()
@ -1269,6 +1436,7 @@ class DefaultExit(DefaultObject):
created dynamically depending on what the exit is called). This created dynamically depending on what the exit is called). This
command (which has a high priority) will thus allow us to traverse command (which has a high priority) will thus allow us to traverse
exits simply by giving the exit-object's name on its own. exits simply by giving the exit-object's name on its own.
""" """
# Helper classes and methods to implement the Exit. These need not # Helper classes and methods to implement the Exit. These need not
@ -1279,23 +1447,26 @@ class DefaultExit(DefaultObject):
""" """
Helper function for creating an exit command set + command. Helper function for creating an exit command set + command.
The command of this cmdset has the same name as the Exit object The command of this cmdset has the same name as the Exit
and allows the exit to react when the player enter the exit's name, object and allows the exit to react when the player enter the
triggering the movement between rooms. exit's name, triggering the movement between rooms.
Args:
exiddobj (Object): The DefaultExit object to base the command on.
Note that exitdbobj is an ObjectDB instance. This is necessary
for handling reloads and avoid tracebacks if this is called while
the typeclass system is rebooting.
""" """
class ExitCommand(command.Command): class ExitCommand(command.Command):
""" """
This is a command that simply cause the caller This is a command that simply cause the caller to traverse
to traverse the object it is attached to. the object it is attached to.
""" """
obj = None obj = None
def func(self): def func(self):
"Default exit traverse if no syscommand is defined." """
Default exit traverse if no syscommand is defined.
"""
if self.obj.access(self.caller, 'traverse'): if self.obj.access(self.caller, 'traverse'):
# we may traverse the exit. # we may traverse the exit.
@ -1333,8 +1504,9 @@ class DefaultExit(DefaultObject):
""" """
Setup exit-security Setup exit-security
You should normally not need to overload this - if you do make sure you You should normally not need to overload this - if you do make
include all the functionality in this method. sure you include all the functionality in this method.
""" """
super(DefaultExit, self).basetype_setup() super(DefaultExit, self).basetype_setup()
@ -1349,28 +1521,32 @@ class DefaultExit(DefaultObject):
def at_cmdset_get(self, **kwargs): def at_cmdset_get(self, **kwargs):
""" """
Called when the cmdset is requested from this object, just before the Called just before cmdsets on this object are requested by the
cmdset is actually extracted. If no Exit-cmdset is cached, create command handler. If changes need to be done on the fly to the
it now. cmdset before passing them on to the cmdhandler, this is the
place to do it. This is called also if the object currently
have no cmdsets.
Kwargs:
force_init (bool): If `True`, force a re-build of the cmdset
(for example to update aliases).
kwargs:
force_init=True - force a re-build of the cmdset (for example to update aliases)
""" """
if "force_init" in kwargs or not self.cmdset.has_cmdset("_exitset", must_be_default=True): if "force_init" in kwargs or not self.cmdset.has_cmdset("_exitset", must_be_default=True):
# we are resetting, or no exit-cmdset was set. Create one dynamically. # we are resetting, or no exit-cmdset was set. Create one dynamically.
self.cmdset.add_default(self.create_exit_cmdset(self), permanent=False) self.cmdset.add_default(self.create_exit_cmdset(self), permanent=False)
# this and other hooks are what usually can be modified safely.
def at_object_creation(self):
"Called once, when object is first created (after basetype_setup)."
pass
def at_traverse(self, traversing_object, target_location): def at_traverse(self, traversing_object, target_location):
""" """
This implements the actual traversal. The traverse lock has already been This implements the actual traversal. The traverse lock has
checked (in the Exit command) at this point. already been checked (in the Exit command) at this point.
Args:
traversing_object (Object): Object traversing us.
target_location (Object): Where target is going.
""" """
source_location = traversing_object.location source_location = traversing_object.location
if traversing_object.move_to(target_location): if traversing_object.move_to(target_location):
@ -1383,19 +1559,17 @@ class DefaultExit(DefaultObject):
# No shorthand error message. Call hook. # No shorthand error message. Call hook.
self.at_failed_traverse(traversing_object) self.at_failed_traverse(traversing_object)
def at_after_traverse(self, traversing_object, source_location):
"""
Called after a successful traverse.
"""
pass
def at_failed_traverse(self, traversing_object): def at_failed_traverse(self, traversing_object):
""" """
This is called if an object fails to traverse this object for some Overloads the default hook to implement a simple default error message.
reason. It will not be called if the attribute "err_traverse" is
defined, that attribute will then be echoed back instead as a Args:
convenient shortcut. traversing_object (Object): The object that failed traversing us.
Notes:
Using the default exits, this hook will not be called if an
Attribute `err_traverse` is defined - this will in that case be
read for an error string instead.
(See also hooks at_before_traverse and at_after_traverse).
""" """
traversing_object.msg("You cannot go there.") traversing_object.msg("You cannot go there.")