veratown-prototype

Location Entry Behavior

Location Entry Behavior is an opt-in feature that applies a private message, standard appearance itemsets, or both when a character enters a configured map location. Operators can define reusable rules by location type and override a rule on an individual location.

Behavior

1. The map publishes observed location transitions. The feature ignores initial position snapshots and disabled locations.
2. A location’s data.entryBehavior override takes precedence over its type’s configured default. If neither exists, legacy behavior for the bunny and park_region location types remains available for compatibility.
3. A selected behavior can send a message, apply a uniformly selected enabled appearance itemset, or do both. Itemsets use the shared AppearanceItemSetService and retain its permission, serialization, observation, and action-journaling guarantees. Conditional itemset variants are resolved against the target’s latest BC-observed appearance when the set is applied; unknown prerequisite evidence does not select a variant. See the shared appearance itemset reference.
4. For type defaults and legacy behavior, an existing data.entryMessage key suppresses the default message, and an existing data.entryAppearance key suppresses the default appearance application. The other default action may still run.
5. A malformed explicit override fails closed instead of silently falling back. An override with enabled: false disables the feature for that location.

This feature does not create timers, track offences, persist per-member state, block other features from releasing appearance items, or retry uncertain writes. Timers configured on appearance itemsets are passed through to BC; the shared appearance action remains the sole journal owner for each mutation.

Configuration and management

The feature reads location-entry-behavior.rules from prototypeGameConfig.rooms.main. Startup inserts a disabled baseline only when neither this key nor the legacy bunny.rules key exists. When both are present, the generic key takes precedence. Existing legacy configuration remains in place and readable.

Room admins can manage it through the world-config commands:

!world config show room main
!world config set room main location-entry-behavior.rules <JSON policy>
!world config unset room main location-entry-behavior.rules

The admin web workspace also provides a Location entry behavior room-config section. Add reusable rules using the location-type dropdown and select appearance itemsets from the shared itemset list. The same validated generic configuration is available through the world-config command and the admin workspace.

Example:

{
    "schemaVersion": 1,
    "enabled": true,
    "messages": {
        "actionFailed": "The configured appearance could not be applied safely."
    },
    "locationTypes": {
        "cage": {
            "enabled": true,
            "message": "Please respect everyone in this cage.",
            "itemSets": [{ "name": "Cage profile", "itemSetKey": "appearance.cage" }]
        },
        "shower": {
            "enabled": true,
            "message": "Welcome to the shower."
        }
    }
}

locationTypes keys are location types from the shared location type catalog. Each rule requires enabled and may include message, itemSets, or both. Itemset keys refer to standard records in prototypeItemSets; manage them with the shared appearance itemset tools.

An individual location can override a type default through its map record’s data metadata:

{
    "entryBehavior": {
        "enabled": true,
        "message": "Welcome to this special cage.",
        "itemSets": [{ "name": "Special profile", "itemSetKey": "appearance.special-cage" }]
    }
}

Use the location editor’s guided Location entry behavior override controls to configure the enabled state, optional message, and appearance itemsets. Choose itemsets from the shared dropdown; use Other location metadata (JSON) only for unrelated metadata. The server validates the override before saving. Existing data.bunnyBehavior records and legacy punishments configuration fields remain readable; new configuration should use entryBehavior and itemSets.

The bunny location type remains in the shared type catalog for existing locations. Renaming this feature does not rename or migrate location records.

Outcomes and verification

Disabled or unconfigured behavior does nothing. Unsupported or disabled itemsets fail without a mutation. Occupied or protected appearance groups remain untouched, and dispatched-but-unobserved writes remain unconfirmed in the normal action journal. The feature does not retry them.

Offline tests cover configuration validation and fallback, type defaults, location overrides, existing-action suppression, appearance itemset selection, action outcomes, location transitions, and listener cleanup. They do not claim to qualify live BC timer expiry.