# Gate Address Book Configuration Guide

## Overview

The Stargate HUD now supports remote address book dialing. When you select a gate and click "Dial" or "Address Book", the HUD requests a list of destinations from that gate. This guide explains how to configure your gates to serve address books.

## Gate Controller Integration

The gate controller skeleton (`stargate_gate_controller_skeleton_v1.lsl`) now includes ADDRESS_BOOK support. When a HUD or DHD sends:

```
DHD|ADDRESS_BOOK|FETCH
```

The gate responds on channel `-708004` with JSON:

```json
{
  "event": "address_book",
  "data": {
    "gate_id": "unique_gate_identifier",
    "entries": [
      {
        "target_short": "ATLANTIS",
        "name": "Atlantis Gate",
        "symbols_csv": "1,3,5,8,13,21,34,0"
      },
      {
        "target_short": "MIDWAY",
        "name": "Midway Station",
        "symbols_csv": "8,9,10,11,12,13,14,0"
      }
    ]
  }
}
```

## Configuration Steps

### Step 1: Edit the Gate Controller

Open `stargate_gate_controller_skeleton_v1.lsl` and locate the `send_address_book_response()` function (around line 165).

Currently it returns an empty entries array:
```lsl
string entries = "";
```

### Step 2: Populate Gate Destinations

Replace the empty string with your gate's address book entries. For each destination gate, add:

```lsl
// Single entry
string entries = "{\"target_short\":\"ATLANTIS\",\"name\":\"Atlantis Gate\",\"symbols_csv\":\"1,3,5,8,13,21,34,0\"}";

// Multiple entries (comma-separated)
string entries = "{\"target_short\":\"ATLANTIS\",\"name\":\"Atlantis Gate\",\"symbols_csv\":\"1,3,5,8,13,21,34,0\"},"
    + "{\"target_short\":\"MIDWAY\",\"name\":\"Midway Station\",\"symbols_csv\":\"8,9,10,11,12,13,14,0\"}";
```

### Step 3: Format Requirements

Each entry requires:

| Field | Description | Example |
|-------|-------------|---------|
| `target_short` | 3-12 char uppercase label | `ATLANTIS` |
| `name` | Full gate name | `Atlantis Gate` |
| `symbols_csv` | Chevron symbols as comma-separated numbers | `1,3,5,8,13,21,34,0` |

**Symbol CSV Format:**
- Each number represents a chevron on the DHD (1-9)
- List numbers in the order they appear on the DHD
- End with `0` to lock the gate
- Example: `1,3,5,8,13,21,34,0` means press buttons 1, 3, 5, 8, 13, 21, 34, then the lock button

### Step 4: Test Your Configuration

1. Wear the HUD near your gate
2. Touch the HUD and select "Discover"
3. Select your gate from the list
4. Click "Address Book"
5. Your configured destinations should appear as buttons

## Advanced: Dynamic Address Books

For gates that maintain multiple address books (per-region, per-grid), you can:

1. **Load from a list at startup:**
   ```lsl
   string address_book_data = fetch_from_local_notecard();
   ```

2. **Query an external API:**
   ```lsl
   send_address_book_http_request();
   ```

3. **Maintain a local registry:**
   - Gates can listen on a registry channel (`-708007`)
   - Periodically update their local copy of all known gates
   - Return the updated list in responses

## Legacy Format Support

The gate controller also supports the legacy pipe-delimited format for backward compatibility:

```
ADDRESS_BOOK|Atlantis=1,3,5,8,13,21,34,0;Midway=8,9,10,11,12,13,14,0
```

The HUD will parse either JSON or this format automatically.

## Troubleshooting

### HUD shows "No entries yet (waiting for gate/API)"

This means:
1. Gate did not respond to ADDRESS_BOOK request, OR
2. Gate responded but with empty entries array

**Fix:** Verify the gate controller is listening on channel `-708005` and responding on channel `-708004`.

### HUD shows entries but wrong ones

The HUD displays whatever the gate provides. Verify your `symbols_csv` values are correct for the destination gates.

### Address book not updating

The HUD requests address book fresh each time you click "Address Book" or "Refresh". If the gate is not updating, check:
1. Gate controller has the new address book data
2. Gate script has been reset (replace script or call reset function)

## Implementation Checklist

- [ ] Gate controller receives `DHD|ADDRESS_BOOK` messages on channel `-708005`
- [ ] Gate responds with JSON on channel `-708004`
- [ ] Response includes `gate_id` (unique identifier)
- [ ] Response includes `entries` array (may be empty initially)
- [ ] Each entry has `target_short`, `name`, and `symbols_csv`
- [ ] Symbol values match actual DHD buttons on destination gates
- [ ] HUD receives response and displays entries (if non-empty)

## Notes

- Gates should EXCLUDE themselves from their address book entries (don't list self as a destination)
- Symbol routing is gate-specific; test each route to ensure it reaches the intended destination
- Multiple gates can share the same address book format for consistency
- The HUD can handle up to 9 address book entries per request (LSL dialog limitation)

---

For more information, see:
- `stargate_wearable_dhd_hud_v1.lsl` - HUD implementation
- `stargate_gate_controller_skeleton_v1.lsl` - Gate controller with ADDRESS_BOOK support
- `REMOTE_SESSION_REFERENCE.md` - Full protocol documentation