veratown-prototype

Delayed Location Appearance

An enabled location can apply a configured appearance itemset after a player enters and remains inside for the configured delay. The trigger is stored in the location’s existing data field; it adds no collection or separate appearance format.

{
    "entryAppearance": {
        "enabled": true,
        "rules": [
            {
                "enabled": true,
                "itemSetKey": "appearance.welcome",
                "delayMs": 5000,
                "conditions": {
                    "mode": "any",
                    "conditions": [
                        {
                            "variable": "wears:ItemArms:HeavyYoke",
                            "operator": "equals",
                            "value": true
                        },
                        {
                            "variable": "occupantCount",
                            "operator": "at_least",
                            "value": 5
                        }
                    ]
                }
            }
        ]
    }
}

Use Configure delayed appearance on entry in the location metadata editor. The itemset key field suggests sets from the existing appearance catalog, and the setting is validated before saving. Optional conditions use a single all (AND) or any (OR) group of 1–16 entries; nested groups are not supported. Up to 16 ordered rules may each choose an itemset, delay, enabled state, and required condition group. The first enabled rule whose conditions match wins. An optional fallback itemset/delay (the legacy top-level fields) is used only when no rule matches; if there is no fallback, no set is applied. delayMs is an integer from zero through 86,400,000 milliseconds (24 hours). The selected itemset must exist and be enabled when the delay expires.

Supported facts include observed appearance (wears:<Group>:<Name> and hasAppearanceGroup:<Group>), occupantCount, hour, dayOfWeek, timeOfDay, playerName, playerNickname, playerTitle, memberNumber, locationName, locationKey, locationType, reputation:<Type>, activePose:<PoseName>, arousalProgress, itemExpression:<Group>:<Name>, itemLocked:<Group>:<Name>, itemRemovalTimeRemainingMs:<Group>:<Name>, hasOwner, hasLover, credits, and featureAvailable:<id>. Reputation is unknown if its type is absent from the latest full character sync. Item facts require an exact worn item; lock status exposes no lock-holder identity. The removal-time value uses BC’s absolute epoch-millisecond timer; zero means the timer elapsed, not that BC removed the item. credits is the current available Veratown balance, excluding reserved credits, not BC Money. Time facts use the optional IANA timeZone (UTC by default). Conditions are checked when the entry is prepared and checked again at delay expiry against the latest room, appearance, occupancy, and time facts. If the selected rule changes while waiting, its pending application is discarded. Missing facts do not match, so an unavailable appearance cannot satisfy an all group; an any group still matches if another condition is known true. The trigger does nothing when no rule or fallback matches. Only casino and shop currently have feature-availability resolvers; other feature IDs are unknown. See the shared condition facts and rules reference for the complete location/door inventory and the admin-web suggestion sources.

If the selected set defines conditional variants, the shared itemset service selects one at application time using the target’s latest BC-observed appearance. These itemset conditions are separate from the location rule conditions above, and unknown prerequisite evidence does not select a variant. See the appearance itemset reference.

Trigger and cancellation

Only a real member-join or observed position entry starts a timer. Initial room syncs and configuration-only recalculations do not apply appearance sets. Leaving the location before the delay expires cancels the pending timer. At expiry the feature reloads the location configuration and verifies that the player is still in the configured room and their latest observed position is still inside the same point or region. A changed or disabled trigger is not applied. Each member/location uses a replaceable deadline while the entry token still guards asynchronous selection and application. A stale callback after cancellation or replacement cannot apply an itemset.

The action uses the shared appearance itemset service and existing guarded, journaled appearance actions. Existing BC permission checks, observed-state matching and itemset validation still apply. The feature applies once per entry, does not retry an uncertain appearance write, and does not undo a set if the player leaves after application has begun. Pending timers are cancelled during plug-in shutdown and are not persisted across process restarts.

This is an itemset application trigger, not a timed-release feature. Any appearance lock timers remain those explicitly configured on the itemset and are handled by BC as documented in the appearance guide. The admin editor offers guided rule controls to add, disable, remove, and reorder itemset rules, plus a condition builder and sample-value preview. The preview is not a live BC authorization or observation.