veratown-prototype

ABCL Region Feature

The ABCL feature is a native Veratown port of the reviewed interactive behavior from abdl-bot. It does not load bc-bot or create a socket. The supervisor owns ABCL consent, eligibility, polling, and task scheduling. A separately deployed helper with the abcl capability observes ABCL messages and performs assigned BC actions and participant-facing communication.

For participant instructions, see the ABCL player guide.

The feature is deliberately fail-closed:

• ABCL stays inactive unless abcl.rules is valid and enabled in the selected runtime database. Missing or invalid ABCL configuration does not prevent the supervisor or its other features from starting.
• The configured location must exist in veratownLocations, be enabled, and have region geometry.
• The configured helper must be enabled for the same room and runtime, have the abcl capability, and be server-observed inside that region before a task is queued.
• The helper rechecks its own and the target’s observed positions, current configuration, and participant consent before each action in a sequence. If the helper leaves, the target leaves, consent changes, or configuration becomes invalid, the sequence stops without supervisor-side BC action or communication fallback.

Database configuration

Store this value under the main room scope in the existing prototypeGameConfig document, using Admin Web’s Game configuration workspace:

{
    "schemaVersion": 1,
    "enabled": true,
    "adultsOnlyRoomConfirmed": true,
    "activeLocationKey": "abdl-region",
    "helperAgentId": "helper-abcl"
}

The activeLocationKey must identify an enabled location with a region definition. Rectangle and exact tile-region geometry use the same containment rules as other map features. The key is room-scoped; the current runtime uses main. No default abcl.rules value is seeded. A missing, disabled, malformed, or unresolved value prevents the ABCL feature from starting. Setting enabled:false while the service is running suspends new actions; removing the key also prevents the next ABCL startup.

The selected runtime database remains fixed:

• RUNTIME_TARGET=test uses veratown_prototype_test.
• RUNTIME_TARGET=production uses veratown_prototype.

The config-copy script does not copy participant consent, transient ABCL observations, or helper tasks. Configure and qualify the test region and helper in the test database before production.

Helper requirements

Register one dedicated helper account in prototypeHelperAgents for the configured helperAgentId. It must have:

• role: "helper" and parentAgentId: "supervisor".
• Matching roomKey, runtimeTarget, and BC memberNumber.
• enabled: true and capabilities containing "abcl".
• Its own RUNTIME_ROLE=helper process and dedicated BC credentials.

The helper and participant must be present in the room and inside the configured region. The helper accepts either its local BC room position or an independent supervisor observation. The authenticated observation stream provides a supervisor snapshot of the current BC room on connect; that session-bound position remains usable while the stream and supervisor BC room session remain valid, until a position update or invalidation replaces it. The helper’s own uploaded observation does not count as independent evidence. A helper startup point may be configured only when the point lies inside the region; a region itself is not a teleport destination. If either participant is absent or no in-region position is available from a valid source, the helper does not dispatch the task. For local position checks, the helper resolves its registered member number against the current BC room snapshot instead of using the potentially stale login character snapshot. The supervisor never sends the helper’s public communication itself. Region rejection logs distinguish whether the local position was available and whether independent position evidence was available and matched, without logging coordinates.

Participant consent and commands

Participation is opt-in and stored per room/member in prototypeAbclConsents. A participant may use the supervisor’s bot-addressed commands or ! forms:

Command	Effect
/bot abcl opt-in / !abcl opt-in	Persist consent and request an ABCL state sync when the participant and helper are both in the active region.
/bot abcl opt-out / !abcl opt-out	Revoke consent, cancel queued ABCL tasks, clear transient state, and fence any running sequence before its next action.
/bot abcl status / !abcl status	Report consent through a helper task when the participant and helper are in the region.
/bot abcl blacklist / !abcl blacklist	Alias for opt-out.
/bot abcl unblacklist / !abcl unblacklist	Alias for opt-in.

Unknown commands are not delegated to other feature suites. Command replies also use the helper; if it is unavailable or outside the region, no supervisor communication fallback is used. Consent defaults to false. Room presence, appearance, chat content, BC mod state, or an admin allowlist never substitutes for participant opt-in.

Room administrators can privately request a fresh check for an opted-in participant in the region:

• !abcl test-check <memberNumber> requests the normal classification, which may produce any normal interaction or none.
• !abcl test-change <memberNumber> requests a change-specific check. It requires a valid mod response received within 60 seconds after dispatch, a recognized diaper, the normal wetness/soiliness thresholds, and a mod setting other than Deny. It does not choose puddle cleanup instead.

Both use the same consent, region, cooldown, task budget, item permission and appearance checks as ordinary interactions. A test does not fabricate mod data or guarantee an action. The response is loosely correlated by participant and time, not proof that the request caused it. A disconnect discards the pending test. The supervisor privately acknowledges that the sync was queued, not that a mod responded or a change succeeded; inspect helper task activity for later results. Deploy updated helpers before using the new test task fields. The existing mod Ask setting remains eligible and the change command uses force: true; obtain the test participant’s explicit agreement.

Behavior and data handling

For opted-in participants inside the active region, the helper observes ABCL messages and executes supervisor-assigned tasks:

• Request and validate the ABCL mod’s Hidden sync response.
• Parse the bounded response and report only a minimized decision category to the supervisor; raw mod statistics are discarded.
• Report ECHO_INFO2 and reviewed adult-denial triggers as fixed signal enums; the supervisor rechecks consent, region, current appearance, and cooldown before deciding whether to enqueue a task.
• Send the related public Chat/Emote sequence, targeted ABCL Hidden command, and guarded appearance changes as typed helper tasks.
• Reply to the ABCL mod’s ECHO_INFO2 handshake while the participant and helper are in the region.

The supervisor checks received decisions and signals approximately every five seconds and owns ABCL task scheduling. Sync requests occur on opt-in, room entry, and selected startup or recovery events; they are not periodic scans. Ordinary sync requests are limited to one per participant per 30 seconds. Queued ABCL tasks have a five-minute lifetime; this allows serialized work to wait in the queue, while the helper still revalidates room presence, region, configuration, and consent before each action. The active behavior never acts on a non-opted-in participant. The helper queries BC item-interaction permission before state-changing interactions. Appearance changes use BcAppearanceAction; the diaper-change sequence removes only the temporary ItemDevices:ChangingTable it added, not every item in that group. If a sequence becomes uncertain, its helper task moves to reconciliation_required or completed_unconfirmed; the task is never blindly replayed. If opt-out interrupts a sequence after the temporary table is observed, the helper may remove only that same item as compensation, and only while the helper and participant remain observed in the configured region. Other appearance changes from any Veratown runtime are serialized against one another by a short-lived, renewed per-room/member mutation lease.

Data boundaries:

Collection	Purpose and retention
prototypeGameConfig	Room-scoped abcl.rules; no default is inserted.
prototypeAbclConsents	Persistent opt-in/out state, consent revision, and update time. No raw messages or mod statistics.
prototypeAbclObservations	One minimized action-decision category per participant; 60-second TTL. Raw ABCL stats are parsed in memory and discarded.
prototypeAbclSignals	Fixed ECHO_INFO2/adult-denial signal enums, member and consent revision only; 60-second TTL. No chat text or raw mod payload.
prototypeHelperTasks	Typed helper action identifiers, target member number, region, consent/config revisions, task lifecycle, and bounded failure stage/reason codes; existing five-day terminal retention. No free-form user text, exception text, or raw mod payload.
prototypeCharacterActionLeases	Short-lived cross-process lock for appearance mutations to one room/member; renewed while the journaled appearance operation is active.
prototypeActions	Normal action lifecycle records; message text, sync payloads, and appearance payloads are not journaled.

The supervisor turns helper-reported decisions and signals into bounded typed tasks. The helper’s task action budget counts one bounded task. Every BC packet still uses the process’s standard 14-packet/1.2-second queue. Raise the configured helper action budget only after test-room qualification if ABCL tasks are expiring before they can be claimed. The helper does not fall back to the supervisor when a budget is exhausted.

Optional ambient region messages can use the same helper through the regional flavor schedule. These public templates are separate from ABCL participant interactions and require communication or emote capability in addition to abcl.

On stop, the supervisor detaches room listeners and stops polling, fences new task creation, then waits for accepted event and poll work to settle before the runtime closes Mongo. An in-progress consent or task write may delay stop; it cannot queue a fresh task after the stop fence.

Runtime roles and deployment

RUNTIME_ROLE selects a static composition:

• supervisor (default): existing Veratown feature set, including ABCL coordination and its opt-in command suite. Missing, disabled, or invalid abcl.rules leaves ABCL inactive without blocking supervisor startup.
• helper: helper worker only; also accepts typed ABCL helper tasks for an abcl-capable helper.

Each process owns one dedicated BC account, one BcClient, and one local rate queue. The supervisor and helper use the same fixed database target and BC room, but separate accounts and processes. Do not deploy a dedicated ABCL controller. Existing database profiles with role abcl remain readable for administrative migration but cannot start; change them to supervisor or disable/retire them. See the ABCL Railway deployment guide.

Qualification and rollback

1. Use RUNTIME_TARGET=test, dedicated test accounts, and an adults-only test room.
2. Create and enable the exact region and ABCL config in the test database.
3. Configure the helper with the abcl capability and confirm its BC-observed position inside the region.
4. Verify opt-out during queued and running work, helper departure, target departure, reconnect, malformed sync payloads, denied item access, and unconfirmed action outcomes.
5. Review redacted action/task metadata and confirm that no raw mod statistics or chat content are persisted.
6. Obtain separate operator approval before enabling production config.

The upstream loop also contains helper-avatar-only expression, pose, and restraint cleanup. Those actions are intentionally not ported: the helper avatar remains operator-managed, and automatically stripping its appearance would race with that ownership. Unreferenced local-money helpers from the upstream repository are not part of its registered main-runtime behavior.

To disable the feature, set enabled:false or unset abcl.rules, then stop the ABCL service. This does not disable the ordinary supervisor or helper service.