__init__ ( self )

Constructor. Do NOT override!

Constructs and initializes the object. If you want to perform some initialization at construction time, override the createObject method. It will be invoked by this constructor after all other initialization has occured.

__repr__ ( self )

Redefines the string representation of game objects.

This primarily is done so that the bluemud OID will be displayed instead of the Python OID.

returns:

(string) module name then classname then our special object id

addAdjective ( self,  newAdjective )

Appends an adjective to this object.

Adjectives are used in automatically-generated short descriptions of objects and interactives can make use of adjectives when describing objects in user commands. Note that adjectives usually appear in descriptions in the order in which they appear in the list of adjectives.

arguments:

newAdjective

(string) the adjective to append to this object

addAttachedObject ( self,  objectToAttach )

Add an object attachment to this object.

An attachment is a viewable extension of the object that can be explicitly examined separately from the object itself (for example, a piece of wood might have an engraving that could be examined). Attachments can take the form of previously constructed objects, in which case this method should be used, or simply a list of identifying names and a description, in which case the addAttachment method should be used.

arguments:

objectToAttach

(object) the object to attach

addAttachment (
        self,
        names,
        *description,
        )

Add an attachment to this object.

An attachment is a viewable extension of the object that can be explicitly examined separately from the object itself (for example, a piece of wood might have an engraving that could be examined). Attachments can take the form of previously constructed objects, in which case the addAttachedObject method should be used, or simply a list of names and a description, in which case this method should be used. The description can be one or more strings or VBFCs. Note that this method will actually dynamically generate a simple object with the given names and description and then attach it to this object.

arguments:

names

(list of strings) all the names for this attachment

*description

(list of strings and VBFCs) when evaluated this is the description that gets returned for those names

addName ( self,  newName )

Appends a name to this object's names list.

Note that this new name does NOT necessarily become the default name. See the setName method if you want to explicitly set the default name.

arguments:

newName

(string) the new name to ADD to this object

addPluralName ( self,  newPluralName )

Appends a plural name to this object's plural names list.

Note that this new plural name does NOT necessarily become the default plural name. See the setPluralName method if you want to explicitly set the default plural name. Plural names are used to reference multiples of an object.

arguments:

newPluralName

(string) the new plural name to ADD to this object

addProperty (
        self,
        propertyName,
        propertyValue,
        )

Add a named property to this object.

The property name must be a string. If the property has a standard definition, then its documentation should be consulted to determine the expected type of the value; otherwise it can be anything you want, including a VBFC.

arguments:

propertyName

(string) the name of the property to set

propertyValue

(anything--consult property documentation) the value of the property

addShadow ( self,  shadowObject )

Adds a new shadow to this object.

Shadows are special objects that provide dynamic runtime extension (see the shadow module for details). This method adds a shadow to this object. This method is typically invoked by the shadow object itself and generally shouldn't be directly invoked otherwise.

arguments:

shadowObject

(mudlib.shadow.Shadow) shadow object to add

canEnterEnvironment ( self,  newEnvironment )

Override to restrict movement of this object into an environment.

This method will be invoked during the movement of this object to a new environment. This method should return true if the object is allowed to enter the new environment, false otherwise. Note that any checks in this method should be above and beyond the normal checks.

arguments:

newEnvironment

(mudlib.core.Container) the new environment this object may be moved to

returns:

(int) 1 if the object can enter the new environment, 0 if not

canLeaveEnvironment ( self,  environment )

Override to restrict movement of this object from its environment.

This method will be invoked during movement of this object out of its environment. This method should return true if the object is allowed to leave its current environment, false otherwise. Note that any checks in this method should be above and beyond the normal checks.

arguments:

environment

(mudlib.core.Container) the environment that this object is leaving?

returns:

(int) 1 if it can leave, 0 if not

createObject ( self )

The psuedo-constructor for game objects.

This method should be overriden and any necessary initialization put in the overriden version. Note that you should NOT override the __init__ method.

destroy ( self )

Pseudo-destructor. Do NOT override! Ever!

This method will be invoked when it's desired that this object be destroyed. It will take care of any cleanup, remove all shadows from this object, and then move this object out of its current environment. Note that you should NOT override this method. If you want to perform your own cleanup, you should override the destroyObject method which is invoked by this method after all other cleanup has been performed.

destroyObject ( self )

Invoked when this object is being destroyed.

This method is invoked by the destroy method after it has performed any necessary cleanup. If you want to do any of your own cleanup, you should override this method.

doSearch (
        self,
        thisPlayer,
        arguments,
        )

This method gets called when someone searches in the room. Return 1 if the search finds something, return 0 otherwise.

arguments:

thisPlayer

(???) the player searching?

arguments

(tuple) the list of arguments?

Override this method so that it returns a 1 if the search finds something and 0 otherwise.

enterEnvironment ( self,  newEnvironment )

Invoked after this object has entered its new environment.

You should override this method if you want to do any special processing when this object enters a new environment. Note that you should NOT generally override the move method.

arguments:

newEnvironment

(mudlib.core.Container) the environment this object just entered

getAdjectives ( self )

Retrieve the list of this object's adjectives.

Adjectives are used in automatically-generated short descriptions of objects, and interactives can make use of adjectives when describing objects in user commands.

returns:

(list of strings) all the adjectives of this object

getAttachments ( self )

Retrieve the attachments hosted by this object.

An attachment is a viewable extension of the object that can be explicitly examined separately from the object itself (for example, a piece of wood that might have an engraving that could be examined).

returns:

(list of something?) ???

getBrightness ( self )

Get the brightness rating of this object

Brightness is a measure of how much light an object emits. For most objects, this will be zero (which is the default).

returns:

(int) the level of brightness for this object.

see setBrightness

getCharacteristics ( self )

Returns the mapping of this object's named characteristics.

A characteristic is an additional description of the object that is automatically appended to the long description.

getEnvironment ( self )

Retrieve the current environment of this object.

The environment of an object will be the container in which this object is directly contained. If this object is not contained by any object, then None will be returned.

returns:

(mudlib.core.Container) the environment this object is in or None

getHeight ( self )

Get this object's height.

returns:

(int) the object's height.

FIXME - what unit of measure is this in?

getLength ( self )

Get this object's length.

returns:

(int) the object's length.

FIXME - what unit of measure is this in?

getLongDescription ( self )

Retrieve the long description of this object.

The long description provides a detailed description of the object, usually obtained through examination of the object. Characteristics of the object are automatically appended to the long description provided via the setLongDescription method.

returns:

(string) the long description string with all VBFCs evaluated

getName ( self )

Retrieve the default name of this object.

Note that, if no "normal" name exists, the first inherent name will be returned.

returns:

(string) the default name of this object

getNames ( self )

Retrieve all of the names associated with this object.

Note that, in addition to "normal" names set via the addName, setName, and/or setNames methods, this method also includes (appended) the "inherent" names of the object.

returns:

(list of strings) all the names of this object

getPluralName ( self )

Retrieve the default plural name of this object.

Plural names are used to reference multiples of an object. Note that inherent plural names are NOT taken into account in this method. Instead, of no plural names have been explicitly provided, the plural form of the default singular name will be returned. This is primarily so that objects for which no explicit plural name has been set will behave intuitively.

returns:

(string) the default plural name of this object

getPluralNames ( self )

Retrieve all of the plural names associated with this object.

Plural names are used to reference multiples of an object. Note that, in addition to the "normal" plural names set on this object via the addPluralName, setPluralName, and setPluralNames methods, this method also includes (appended) the "inherent" plural names of this object. Also note that, if no "normal" plural names have been explicitly set, then this method will instead return the plural form of the singular names (plus the inherent plural names).

returns:

(list of strings) the list of all plural names of this object

getPluralShortDescription ( self )

Retrieve the plural short description of this object.

The plural short description describes multiple instances of an object at a glance. Note that, if a plural short description is not explicitly provided via the setPluralShortDescription method, one will be automatically generated from the object's default plural name--or plural form of the default singular name if a plural name has not been explicitly set--and adjectives (which should be sufficient for most objects).

returns:

(string) the short plural description string with all VBFCs evaluated or a string of all the adjectives and the defualt plural name

getProperties ( self )

Retrieves the dictionary of properties added to this object.

returns:

(hash) the hashmap of all the properties

getProperty (
        self,
        propertyName,
        default=None,
        )

Retrieve the value of the property with the given name.

Returns the value of the property previously added to this object under the given name. If no property has been added to this object under that name, then the default is returned. If the value of the property is a VBFC, then it will be evaluated and its return value will be returned. Otherwise the actual value of the property is returned.

arguments:

propertyName

(string) the name of the property to retrieve

default=None

(anything) whatever you want the default to be if the property doesn't exist

returns:

the property value or the default

getShortDescription ( self )

Retrieve the short description of this object.

The short description describes this object at a glance. Note that, if a short description was not explicitly provided via the setShortDescription method, one will be automatically generated from the object's default name and adjectives (which should be sufficient for most objects).

returns:

(string) the short description string with all VBFCs evaluated or a string of all the adjectives and the defualt name

getVolume ( self )

Get this object's volume

returns:

(int) the object's volume (length width height)

FIXME - what unit of measure is this in?

getWeight ( self )

Get this object's weight

returns:

(int) the object's weight.

FIXME - what unit of measure is this in?

getWidth ( self )

Get this object's width.

returns:

(int) the object's width.

FIXME - what unit of measure is this in?

isShadowed ( self )

Determine if this object is shadowed.

returns:

(int) 1 if object is shadowed, 0 if not

leaveEnvironment ( self,  oldEnvironment )

Invoked after this object has left its previous environment.

You should override this method if you want to do any special processing when this object leaves an environment. Note that you should NOT generally override the move method.

arguments:

oldEnvironment

(mudlib.core.Container) the old environment this object was in

load ( self,  variableMapping )

Recreate a previously persisted object.

This method may be invoked by the stdlib.loadObject function during recreation of this object from persistence. It will be passed a mapping equivalent to the one returned by this object's save method when the object was persisted. This method is responsible for restoring this object back to its original state.

If this object is intended to be persisted, then this method should be overriden to rebuild the object from the saved state map returned by the save method.

arguments:

variableMapping

hashmap of property names and values

move ( self,  container )

Move this object into the given container.

Note that you should NOT generally override this method. If you're interested in doing special processing when this object leaves its current environment, override the leaveEnvironment method. If you're interested in doing special processing when this object enters a new environment, override the enterEnvironment method. If you're interested in restricting movement of the object, override one or both of the cannotLeaveEnvironment or cannotEnterEnvironment methods.

arguments:

container

(mudlib.core.Container) the target container

returns:

(int) 1 if the object moved successfully, and 0 if not.

objectEnteredEnvironment ( self,  newObject )

Invoked when another object enters this object's environment.

If you want to do any special processing when another object enters the environment of this object, then you should override this method.

arguments:

newObject

(object) the object that just entered this environment

objectLeftEnvironment ( self,  oldObject )

Invoked when another object leaves this object's environment.

If you want to do any special processing when another object leaves the environment of this object, then you should override this method.

arguments:

oldObject

(object) the object that just left the environment

popShadow ( self )

Removes the shadow most recently added to this object.

Shadows are special objects that provide dynamic runtime extension (see the shadow module for details). This method removes the shadow most recently added to this object. This method is typically invoked by the shadow object itself and generally shouldn't be directly invoked otherwise.

returns:

(mudlib.shadow.Shadow) the last shadow

refreshObject ( self )

Invoked periodically to refresh this object's state.

This method is invoked every so often to allow the object to refresh and reset itself back to a known state, if desired. It can also be used to progress through a series of known states (for example, a piece of fruit could override this method and progress through another step of ripening and, eventually, decay).

If you need to periodically refresh the state of the object or take some kind of cleanup or progression action, you should override this method.

removeAdjective ( self,  oldAdjective )

Remove an adjective from this object.

Adjectives are used in automatically-generated short descriptions of objects, and interactions can make use of adjectives when describing objects in user commands.

arguments:

oldAdjective

(string) the adjective to remove from this object

removeAttachedObject ( self,  objectToRemove )

Removes an attachment from this object via object reference.

This method will remove the given object from this object's attachments. This method is convenient if the attachment was added via the addAttachedObject method.

arguments:

objectToRemove

(object) the object to remove

removeAttachment ( self,  primaryName )

Removes an attachment from this object via object name.

This method will remove any attachments from this object for which a call to its getName method returns a name matching the given primaryName. This method is convenient if the attachment was added via the addAttachment method.

arguments:

primaryName

(string) the name of the attachment to remove

removeCharacteristic ( self,  name )

Remove a named characteristic from this object.

A characteristic is an additional description of the object that is automatically appended to the long description.

arguments:

name

(string) the name of the characteristic to remove

removeName ( self,  targetName )

Remove a name from this object's names list.

arguments:

targetName

(string) the name to remove from this object

removeProperty ( self,  propertyName )

Remove the property with the given name from this object.

arguments:

propertyName

(string) the name of the property to remove

save ( self )

Retrieve a mapping of object state that should be persisted.

This method may be invoked by the stdlib.saveObject function during persistence of this object. This method should return a mapping of values that should be saved in order to later restore this object back to its current state.

If this object is intended to be persisted, then this method should be overriden to return a map of state to be saved.

returns:

(hash) the mapping of the object state or None if this object doesn't support saving state

setAdjectives ( self,  adjectives )

Set all of this object's adjectives at once.

Adjectives are used in automatically-generated short descriptions of objects, and interactives can make use of adjectives when describing objects in user commands. Note that adjectives usually appear in descriptions in the order in which they appear in the list of adjectives.

arguments:

adjectives

(list of strings) the list of adjectives to assign to this object all at once

setBrightness ( self,  brightness )

Set the brightness rating of this object.

Brightness is a measure of how much light an object emits. For most objects, this will be zero (which is the default).

arguments:

brightness

(int) the level of brightness to set

FIXME - what would be examples of brightness levels?

setCharacteristic (
        self,
        name,
        *description,
        )

Set a named characteristic on this object.

A characteristic is an additional description of the object that is automatically appended to the object's long description. For example, a door might use a characteristic to indicate whether it's open or closed. Note that, if this object already has a characteristic with the provided name, then that characteristic will be altered with the provided description. The description argument can be one or more strings or VBFCs.

arguments:

name

(string) the name of the characteristic to set

*description

(list of VBFCs and strings) the characteristic text of this object

setHeight ( self,  height )

Set this object's height.

arguments:

height

(int) the height of this object

FIXME - what unit of measure is this in?

setLength ( self,  length )

Set this object's length.

arguments:

length

(int) the object's length

FIXME - what unit of measure is this in?

setLongDescription ( self,  *description )

Set the long description of this object.

The long description should be a detailed description, usually obtained through examination of the object. Arguments can be one or more strings or VBFCs. Note that characteristics will automatically be appended to the given description.

arguments:

*description

(list of VBFCs and strings) the long description of this object

setName ( self,  newName )

Sets this object's default name (what the getName method returns).

arguments:

newName

(string) the new name to assign to this object

setNames ( self,  names )

Set all of this object's names at once.

Replaces this object's current list of names with the given list of names. Note that objects also maintain separately a list of inherent names, which are appended to the list of "normal" names and returned by the getNames method. So using this method to reset all of the names of an object doesn't necessarily result in getNames returning just the given list of names.

arguments:

names

(list of strings) the list of names to give this object

setPluralName ( self,  newPluralName )

Sets this object's default plural name

The plural name is returned by the getPluralName method and is used when multiple instances of like objects are the subject of a command.

arguments:

newPluralName

(string) sets the plural name of this object

setPluralNames ( self,  pluralNames )

Set all of this object's plural names at once.

Replaces this object's current list of plural names with the given list of plural names. Note that objects also maintain a separate list of "inherent" plural names which are appended to the list of "normal" plural names and returned by the getPluralNames method. So using this method ot reset all of the plural names of an object doesn't necessarily result in getPluralNames returning just the given list of plural names. Plural names are used to reference multiples of an object.

arguments:

pluralNames

(list of strings) the list of plural names to assign to this object

setPluralShortDescription ( self,  *description )

Sets the plural short description of this object.

The plural short description should describe multiple instances of an object at a glance. Arguments can be one or more strings or VBFCs. Note that, if a plural short description is not explicitly provided, one will be automatically generated from the object's default plural name--or plural form of the default singular name if a plural name has not been explicitly set--and adjectives (which should be sufficient for most objects).

arguments:

*description

(list of VBFCs and strings) the plural short description of this object

setShortDescription ( self,  *description )

Set the short description of this object.

The short description should describe the object at a glance. Arguments can be one or more strings or VBFCs. Note that, if a short description is not explicitly provided, one will be automatically generated from the object's default name and adjectives (which should be sufficient for most objects).

arguments:

*description

(list of VBFCs and strings) the short description of this object

setWeight ( self,  weight )

Set this object's weight.

arguments:

weight

(int) the object's weight

FIXME - what unit of measure is this in?

setWidth ( self,  width )

Set this object's width.

arguments:

width

(int) the object's width

FIXME - what unit of measure is this in?