evennia.contrib.extended_room

Extended Room

Evennia Contribution - Griatch 2012, vincent-lg 2019

This is an extended Room typeclass for Evennia. It is supported by an extended Look command and an extended desc command, also in this module.

Features:

1. Time-changing description slots

This allows to change the full description text the room shows depending on larger time variations. Four seasons (spring, summer, autumn and winter) are used by default. The season is calculated on-demand (no Script or timer needed) and updates the full text block.

There is also a general description which is used as fallback if one or more of the seasonal descriptions are not set when their time comes.

An updated desc command allows for setting seasonal descriptions.

The room uses the evennia.utils.gametime.GameTime global script. This is started by default, but if you have deactivated it, you need to supply your own time keeping mechanism.

2. In-description changing tags

Within each seasonal (or general) description text, you can also embed time-of-day dependent sections. Text inside such a tag will only show during that particular time of day. The tags looks like <timeslot> … </timeslot>. By default there are four timeslots per day - morning, afternoon, evening and night.

3. Details

The Extended Room can be “detailed” with special keywords. This makes use of a special Look command. Details are “virtual” targets to look at, without there having to be a database object created for it. The Details are simply stored in a dictionary on the room and if the look command cannot find an object match for a look <target> command it will also look through the available details at the current location if applicable. The @detail command is used to change details.

4. Extra commands

CmdExtendedRoomLook - look command supporting room details CmdExtendedRoomDesc - desc command allowing to add seasonal descs, CmdExtendedRoomDetail - command allowing to manipulate details in this room

as well as listing them

CmdExtendedRoomGameTime - A simple time command, displaying the current

time and season.

Installation/testing:

Adding the ExtendedRoomCmdset to the default character cmdset will add all new commands for use.

In more detail, in mygame/commands/default_cmdsets.py:

… from evennia.contrib import extended_room # <-new

class CharacterCmdset(default_cmds.Character_CmdSet):

… def at_cmdset_creation(self):

… self.add(extended_room.ExtendedRoomCmdSet) # <-new

Then reload to make the bew commands available. Note that they only work on rooms with the typeclass ExtendedRoom. Create new rooms with the right typeclass or use the typeclass command to swap existing rooms.

class evennia.contrib.extended_room.ExtendedRoom(*args, **kwargs)

Bases: evennia.objects.objects.DefaultRoom

This room implements a more advanced look functionality depending on time. It also allows for “details”, together with a slightly modified look command.

at_object_creation()

Called when room is first created only.

get_time_and_season()

Calculate the current time and season ids.

replace_timeslots(raw_desc, curr_time)

Filter so that only time markers <timeslot>…</timeslot> of the correct timeslot remains in the description.

Parameters

• raw_desc (str) – The unmodified description.

• curr_time (str) – A timeslot identifier.

Returns

description (str) – A possibly moified description.

return_detail(key)

This will attempt to match a “detail” to look for in the room.

Parameters

key (str) – A detail identifier.

Returns

detail (str or None) – A detail matching the given key.

Notes

A detail is a way to offer more things to look at in a room without having to add new objects. For this to work, we require a custom look command that allows for look <detail> - the look command should defer to this method on the current location (if it exists) before giving up on finding the target.

Details are not season-sensitive, but are parsed for timeslot markers.

set_detail(detailkey, description)

This sets a new detail, using an Attribute “details”.

Parameters

• detailkey (str) – The detail identifier to add (for aliases you need to add multiple keys to the same description). Case-insensitive.

• description (str) – The text to return when looking at the given detailkey.

del_detail(detailkey, description)

Delete a detail.

The description is ignored.

Parameters

• detailkey (str) – the detail to remove (case-insensitive).

• description (str, ignored) – the description.

The description is only included for compliance but is completely ignored. Note that this method doesn’t raise any exception if the detail doesn’t exist in this room.

return_appearance(looker, **kwargs)

This is called when e.g. the look command wants to retrieve the description of this object.

Parameters

• looker (Object) – The object looking at us.

• **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

Returns

description (str) – Our description.

update_current_description()

This will update the description of the room if the time or season has changed since last checked.

exception DoesNotExist

Bases: evennia.objects.objects.DefaultRoom.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultRoom.MultipleObjectsReturned

path = 'evennia.contrib.extended_room.ExtendedRoom'

typename = 'ExtendedRoom'

class evennia.contrib.extended_room.CmdExtendedRoomLook(**kwargs)

Bases: evennia.commands.default.general.CmdLook

look

Usage:

look look <obj> look <room detail> look *<account>

Observes your location, details at your location or objects in your vicinity.

func()

Handle the looking - add fallback to details.

aliases = ['l', 'ls']

help_category = 'general'

key = 'look'

lock_storage = 'cmd:all()'

class evennia.contrib.extended_room.CmdExtendedRoomDesc(**kwargs)

Bases: evennia.commands.default.building.CmdDesc

desc - describe an object or room.

Usage:

desc[/switch] [<obj> =] <description>

Switches for desc:

spring - set description for <season> in current room. summer autumn winter

Sets the “desc” attribute on an object. If an object is not given, describe the current room.

You can also embed special time markers in your room description, like this:

<night>In the darkness, the forest looks foreboding.</night>.

Text marked this way will only display when the server is truly at the given timeslot. The available times are night, morning, afternoon and evening.

Note that seasons and time-of-day slots only work on rooms in this version of the desc command.

aliases = ['describe']

switch_options = ()

reset_times(obj)

By deleteting the caches we force a re-load.

func()

Define extended command

help_category = 'building'

key = 'desc'

lock_storage = 'cmd:perm(desc) or perm(Builder)'

class evennia.contrib.extended_room.CmdExtendedRoomDetail(**kwargs)

Bases: evennia.commands.default.muxcommand.MuxCommand

sets a detail on a room

Usage:

@detail[/del] <key> [= <description>] @detail <key>;<alias>;… = description

Example

@detail @detail walls = The walls are covered in … @detail castle;ruin;tower = The distant ruin … @detail/del wall @detail/del castle;ruin;tower

This command allows to show the current room details if you enter it without any argument. Otherwise, sets or deletes a detail on the current room, if this room supports details like an extended room. To add new detail, just use the @detail command, specifying the key, an equal sign and the description. You can assign the same description to several details using the alias syntax (replace key by alias1;alias2;alias3;…). To remove one or several details, use the @detail/del switch.

key = '@detail'

locks = 'cmd:perm(Builder)'

help_category = 'building'

func()

This is the hook function that actually does all the work. It is called by the cmdhandler right after self.parser() finishes, and so has access to all the variables defined therein.

aliases = []

lock_storage = 'cmd:perm(Builder)'

class evennia.contrib.extended_room.CmdExtendedRoomGameTime(**kwargs)

Bases: evennia.commands.default.muxcommand.MuxCommand

Check the game time

Usage:

time

Shows the current in-game time and season.

key = 'time'

locks = 'cmd:all()'

help_category = 'general'

func()

Reads time info from current room

aliases = []

lock_storage = 'cmd:all()'

class evennia.contrib.extended_room.ExtendedRoomCmdSet(cmdsetobj=None, key=None)

Bases: evennia.commands.cmdset.CmdSet

Groups the extended-room commands.

at_cmdset_creation()

Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

path = 'evennia.contrib.extended_room.ExtendedRoomCmdSet'