the-nexus/EVENNIA_NEXUS_EVENT_PROTOCOL.md

Evennia → Nexus Event Protocol

This is the thin semantic adapter between Timmy's persistent Evennia world and Timmy's Nexus-facing world model.

Principle:

• Evennia owns persistent world truth.
• Nexus owns visualization and operator legibility.
• The adapter owns only translation, not storage or game logic.

Canonical event families

1. evennia.session_bound

Binds a Hermes session to a world interaction run.

{
  "type": "evennia.session_bound",
  "hermes_session_id": "20260328_132016_7ea250",
  "evennia_account": "Timmy",
  "evennia_character": "Timmy",
  "timestamp": "2026-03-28T20:00:00Z"
}

2. evennia.actor_located

Declares where Timmy currently is.

{
  "type": "evennia.actor_located",
  "actor_id": "Timmy",
  "room_id": "Gate",
  "room_key": "Gate",
  "room_name": "Gate",
  "timestamp": "2026-03-28T20:00:01Z"
}

3. evennia.room_snapshot

The main room-state payload Nexus should render.

{
  "type": "evennia.room_snapshot",
  "room_id": "Chapel",
  "room_key": "Chapel",
  "title": "Chapel",
  "desc": "A quiet room set apart for prayer, conscience, grief, and right alignment.",
  "exits": [
    {"key": "courtyard", "destination_id": "Courtyard", "destination_key": "Courtyard"}
  ],
  "objects": [
    {"id": "Book of the Soul", "key": "Book of the Soul", "short_desc": "A doctrinal anchor."},
    {"id": "Prayer Wall", "key": "Prayer Wall", "short_desc": "A place for names and remembered burdens."}
  ],
  "occupants": [],
  "timestamp": "2026-03-28T20:00:02Z"
}

4. evennia.command_issued

Records what Timmy attempted.

{
  "type": "evennia.command_issued",
  "hermes_session_id": "20260328_132016_7ea250",
  "actor_id": "Timmy",
  "command_text": "look Book of the Soul",
  "timestamp": "2026-03-28T20:00:03Z"
}

5. evennia.command_result

Records what the world returned.

{
  "type": "evennia.command_result",
  "hermes_session_id": "20260328_132016_7ea250",
  "actor_id": "Timmy",
  "command_text": "look Book of the Soul",
  "output_text": "Book of the Soul. A doctrinal anchor. It is not decorative; it is a reference point.",
  "success": true,
  "timestamp": "2026-03-28T20:00:04Z"
}

What Nexus should care about

For first renderability, Nexus only needs:

• current room title/description
• exits
• visible objects
• actor location
• latest command/result

It does not need raw telnet noise or internal Evennia database structure.

Ownership boundary

Do not build a second world model in Nexus. Do not make Nexus authoritative over persistent state. Do not make Evennia care about Three.js internals.

Own only this translation layer.