# Evennia World Bridge System

## Components

### 1. Gateway (`world/gateway.py`)
- `GatewayRoom` typeclass: A room that connects to another world
- `TravelExit`: An exit that leads to another world
- Properties: destination_url, destination_room, bridge_active, visitors

### 2. Bridge API (`world/bridge_api.py`)
- HTTP server on port 4003
- Endpoints:
  - `GET /bridge/state` — Get current world state
  - `GET /bridge/health` — Check world health
  - `POST /bridge/sync` — Sync state from another world

### 3. Bridge Daemon (`world/bridge_daemon.py`)
- Polls remote world for state changes
- Syncs characters, events, and state
- Usage: `python world/bridge_daemon.py --remote http://vps:4003 --poll 5`

### 4. Migration Tool (`world/migrate.py`)
- Export world state: `python world/migrate.py export --output world.json`
- Import world state: `python world/migrate.py import --input world.json`

## Setup

### On Mac (Timmy's World)
```bash
cd ~/.timmy/evennia/timmy_world
# Start bridge API
python world/bridge_api.py &
# Start bridge daemon
python world/bridge_daemon.py --remote http://143.198.27.163:4003 --poll 5
```

### On VPS (The Wizard's Canon)
```bash
cd /root/workspace/timmy-academy
# Start bridge API on port 4003
python world/bridge_api.py &
# Configure GatewayRoom with destination_url
```

## How It Works

1. **Portal Rooms**: Both worlds have a GatewayRoom configured with destination_url
2. **Bridge API**: Each world runs a bridge_api.py server
3. **Bridge Daemon**: Polls remote world every 5 seconds
4. **Travel Command**: Characters can use `travel [room]` to cross worlds
5. **Sync**: Characters, events, and state sync between worlds

## Events That Sync

- Character arrivals/departures
- Messages spoken in portal rooms
- World events (fire, rain, growth)
- Trust changes (limited sync)

## Current Status

- **Prototype**: Code structure created
- **Not Tested**: Bridge not yet tested with real Evennia instances
- **Next Steps**: 
  1. Test bridge API on Mac world
  2. Add GatewayRoom to Mac world (Threshold or Gate)
  3. Configure destination_url to point to VPS
  4. Test on VPS world
  5. Test travel command
  6. Test character sync
