New version of the ExtendedRoom contrib

[Griatch]

The ExtendedRoom contrib is an optional extension to the normal Room, adding the ability to have season-specific descriptions as well as embed markers in said descriptions of the type <morning>The morning sun shines in through the window.</morning> that only shows when in-game time matches the seasons/game time. The room also introduced details, allowing you to look at things in the room without having to create a database object first.

Thing I first wrote ExtendedRoom more than a decade ago, and while it was refactored a bit along the way, the age shows; the code is pretty messy and things are implemented in ways that I would not do today.

So I have refactored the ExtendedRoom as well as dramatically expanded on its functionality. This not only comes with a complete rewrite of the code (using AttributeProperties etc), it also makes it a lot more flexible and usable. I have aimed to keep it backwards-compatible as much as possible though. So no old unit tests fail with this new code.

Functionality of the new version of ExtendedRoom:

Room states

With the new roomstate command (supported by the .room_state property and the add/remove_room_state methods on the room) you can now assign any state to the room, such as burning, flooded, crowded etc. Any number of states can be added. Internally, these are stored as tags on the room, and the roomstate command just toggles a state on/off.

There are three special room-states:

• Seasonal states ("spring", "summer", "autumn", "winter") - unless overridden explicitly, these are always available on the room and will automatically change by the in-game seasons.
• Time-of-day states ("morning", "afternoon", "evening", "night"). These also always available and change automatically according to the in-game time.
• No state. If there are no active states (or you didn't create any descs tied to a particular state), then the plain old desc Attribute will be used, like on a normal room.

Before, the seasons and clock behaviors were hard-coded in the contrib module. Now they are just defined on the class, so to override you can just inherit from the class and change how they work.

Stateful room descriptions

The reworked custom @desc command (.add_desc(text, room_state=...)), one can add state-ful room descriptions. These will be stored as desc_<room_state> Attributes on the room. The normal 'stateless' description still sits in room.db.desc.

Seasonal descriptions work just like other descriptions, but for them to automatically change, they should of course use the correct room state ("spring", "autumn" etc).

In-description markup

All descriptions are parsed on the fly by a new FuncParser callable: state: You embed this to have optional parts of your description. For example, inside an autumn description may be:

The ground is covered in yellow leaves. $state(burning, Heavy smoke drifts between the trees as the forest burns!)

The latter part of this description will only show if the burning room-state has been set on the room. Any room-state can be checked for this way. The time-slot states are no different, just enter $state(morning, The morning sun sifts through the trees.) and this will only show when it's actually morning in your game world.

A cool feature is that the FuncParser parsing the description actually passes the looker (who is looking) into the inlinefunc as well. This is not used by default, but it means if you customize the $state inline (or add another inline) you could create optional parts of the description that actually looks different to different people!

To be backwards-compatible, the room class still supports <morning>...</morning> like before. But note that this syntax only works for time slots, not for any other room-states (the old room implementation was very limited in this regard).

Details

This works as before - you can assign details (stored in a dictionary) and a custom look command means you can investigate details without having to create a new database object for it. It's supported by a cleaned up detail command.

Message echoes

A simple function to have random messages eppear in the room. This is not supported by any command; you just add a list of strings as the Attribute room_messages, set room_message_rate > 0 and either reload the server or call .start_repeat_broadcast_messages() to get the random messages start appearing.

Some help needed

This is currently in latest main branch. It would be good to get some feedback from people who used the old ExtendedRoom to see if this change breaks your flow or not and if we need to add some more things to make it even more backwards-compatible.

[homeofpoe]

From a user standpoint, these changes are terrific and are some components I was planning to design into my own game. Thank you for this elegant and helpful updated version!

[InspectorCaracal]

I don't use the old system so I'm no help there, but this looks great! One curiosity question, though: is there a reason you didn't use the new TagCategoryProperty for room states?

[Griatch]

@InspectorCaracal Since room-states are dynamic and are intended to be possible to change in-game (such as by a builder or gm), it does not make sense to hard-code them as an TagCategoryProperty. A TagCategoryProperty properties is more for if the room itself should be of a certain 'type' without making it a special typeclass.

[InspectorCaracal]

Ohhhh... I must have misunderstood how the new property works, then, I thought you could add/remove tags to and from it.

(Or rather, I thought it acted as a convenience property for accessing and managing the tags on an object within a specific hard-coded category.)

[Griatch]

No, it's not how it works today - it will strive to keep the tags on the object in sync with what the TagCategoryProperty specifies. Maybe it would make more sense to treat the values as 'defaults' though, I can see it being confusing if adding the tag via some other means.

[Griatch]

I reworked this a bit - the TagCategoryProperty will show all tags of the given category - also those added separately in the TagHandler. But it will only itself set the tags given to it in its constructor. So I think this is the most intuitive working. Adding/Removing explicitly from it would make it a handler, which it is not. I've greatly expanded the docs to elaborate more on this.