Simula uses event payloads to trigger AI character reactions during gameplay. Events contain game state, player actions, and priority levels that enable contextual character interactions.

Event Payload

{
  "id": "uuid-v4",
  "timestamp": 1704067700000,
  "userId": "xxxx"
  "characterId":
  "game": {
    "name": "chess",
    "description": "Classical game of chess"
  },
  "event": {
    "priority": 3,
    "what": "piece_captured",
    "description": "User captured a piece! AI lost their Queen.",
    "params": {
      "piece": "q",
      "pieceName": "Queen",
      "capturedBy": "user",
      "loser": "ai"
    }
  },
  "state": {
    "userColor": "white",
    "capturedByUser": ["p", "n", "q"],
    "capturedByAI": ["p"],
    "difficulty": "medium"
  }
}

Priority Levels

Priority Meaning Default Behavior
3 Game start/end, major moments Always triggers reaction
2 Notable mid-game actions Triggers reaction (recommended threshold)
1 Minor updates Filtered out by default

Simula filters events before sending based on your configured min_priority.

Integration Options

All integrations use HTTPS POST (polling is possible but requires custom setup). Simula sends requests to your endpoint and expects a character message in response.

Option Simula Sends You Handle Best For
A: We prompt LLM-ready prompt Forwarding to your LLM, returning the response Quick integration
B: You prompt Raw event + context Prompt engineering, message history, LLM calls Maximum control
C: We handle everything — Nothing (cost deducted from ad revenue) Fastest setup

Option A: Provide your LLM endpoint. We send a formatted prompt with the user, character, and conversation elements passed from the SDK; you return the generated message.

Option B: Provide your game response endpoint. We send the event payload; you construct the prompt, use memory + character descriptions etc., call your LLM, and return the message.

Option C: We manage the full pipeline using our LLM infrastructure.

Example Events by Game

Game Priority 3 Priority 2 Priority 1
Blackjack game_start, game_end — —
Roulette game_start, game_end — —
Chess game_start, game_end, piece_captured check move_made
Apes TD game_start, game_end, wave_complete tower_placed, hp_threshold_50, hp_threshold_25 —
Monopoly Run game_start, game_over milestone_reached buff_gained
Thrillzz player_profile_viewed, running_game_start, running_game_end, game_end heartbeat_tick —