How it Works

AI Virtual Town uses a realtime frontend and a backend NPC manager.

System loop

1. The browser connects over WebSocket.
2. The backend sends the current town state.
3. NPCs run periodic ticks while viewers are active.
4. Each tick chooses a task, local ambient action, or LLM decision.
5. The backend broadcasts movement, speech, emote, idle, and reasoning events.
6. The frontend renders the map, feed, resident state, and reasoning panel.

Cost controls

The backend avoids unnecessary AI calls:

• no active viewers means NPC ticks pause,
• idle/background browsers disconnect after a timeout,
• local ambient speech can keep the town alive without calling the LLM,
• concurrency and rate limits protect the model API.