# 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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.