# Stargate Simulator Performance And API Offload Guide

## Objective

Keep in-world scripts responsive while preventing simulator lag by pushing heavy logic to the API whenever possible.

## Offload Matrix

1. Keep in script (fast, local, low-cost):
- touch interactions
- short state transitions
- local light and sound triggers
- immediate safety checks

2. Prefer API (heavy, variable, or global):
- route resolution and address book lookup
- gate directory and discovery across regions/grids
- GDO/IDC authorization and allow-list persistence
- audit logging and history
- policy decisions and feature flags

## Script Budget Rules

1. No high-frequency polling loops.
2. Avoid long llSleep chains in critical control scripts.
3. Prefer event-driven messaging over timers.
4. Throttle broadcasts and discovery responses.
5. Keep in-memory lists bounded and prune stale entries.

## Current Performance Controls In This Project

1. Native same-region registry responses are throttled.
2. Known-region gate cache uses TTL pruning.
3. Status, AV, and gate control are split across specialized scripts.
4. Heavy persistence is expected to move to API/database.

## Recommended API Endpoints For Offload

1. POST /api/gates/resolve-short
2. GET /api/gates/nearby?region=<name>
3. POST /api/security/idc/authorize
4. POST /api/gates/events
5. GET /api/gates/:id/address-book

## Current Route Auth Bridge Contract

Gate script now supports API-first route auth over the region relay channel.

Request:
API|ROUTE_AUTH|REQ|source_short|mode|route|dest_sim|grid_endpoint|grid_id|target_short

Response:
API|ROUTE_AUTH|OK|reason
API|ROUTE_AUTH|DENY|reason

Timeout behavior:
1. If API reply times out, local fallback can continue if enabled.
2. If local fallback is disabled, dial fails with route_auth_timeout.

## Deployment Guidance

1. Start with local fallback logic enabled for resilience.
2. Move each heavy feature to API one-by-one and keep local fallback.
3. Log script runtime and event latency during load tests.
4. Disable local fallback paths when API reliability is proven.