SDK Install

Recommended 0.1v workflow: set World Rules in Vibe Console, then let your game send events and react to live NPC state updates.

Godot 3.6 SDK

Download the SDK zip or copy the addon folder into your project.

Download SDK (.zip)

Godot 4.5 SDK

Download the SDK zip or copy the addon folder into your project.

Download SDK (.zip)

STEP 01

Copy files into your Godot project

Inside your Godot project, create this folder if it doesn’t exist:

res://addons/chronos/

Then copy these files into res://addons/chronos/:

Chronos.gd
ChronosRESTClient.gd
ChronosSSEClient.gd
ChronosTypes.gd
plugin.gd
plugin.cfg

Keep your project config script here (developers only edit credentials):

res://scripts/chronos_setup.gd

STEP 02

Enable the plugin

• Open Project → Project Settings → Plugins
• Find Chronos and set it to Enabled

This makes the SDK available to your game code.

STEP 03

Configure your world

Recommended: add Chronos as an AutoLoad so you can call it from anywhere.

• Open Project → Project Settings → AutoLoad

• Add these paths and enable them:

res://addons/chronos/Chronos.gd

res://scripts/chronos_setup.gd

Recommended setup script (chronos_setup.gd):

extends Node

func _ready():
  print("SETUP: running chronos_setup.gd")

  Chronos.configure(
    "https://YOUR-VERCEL-URL",
    "CHRONOS_xxxxx",
    "game_id",      # example: "village_reputation"
    "npc_id"        # example: "guard_1"
  )

  # Plug-and-play runtime:
  # auto brain = on
  # debounce = 2 sec
  # max_events = 50
  Chronos.configure_runtime(true, 2, 50)

  Chronos.start()

  print("SETUP: Chronos configured + started")

Tip: Use the Vibe Console first. Generate an API key, set World Rules, then test events and state before wiring gameplay.

STEP 04

Call the SDK in your game code

This is the official 0.1v flow: game sends events → Chronos stores memory → Brain derives NPC state → game reacts to updates.

Important Call 1 — Listen for NPC state updates

Your game should listen for updates from Chronos. When the Brain processes world events, the updated NPC state will be pushed back to the game.

Chronos.npc_state_updated.connect(_on_npc_state_updated)

Example:

 # Example handler for NPC updates

func _on_npc_state_updated(row):

    var npc_id = row["npc_id"]
    var state = row["state"]

    print("NPC state updated:", npc_id, state)
    
    
    # Example in a real game:
    func _on_npc_state_updated(row):

    var state = row["state"]

    if state["mood"] == "hostile":
        guard_attack_player()

    if state["mood"] == "friendly":
        guard_allow_entry()

Your game reacts to NPC behavior changes here.

Important Call 2 — Send gameplay events

When something important happens in your game, send it to Chronos.

Chronos.append_event(
  "player_1",
  event_type,
  payload,
  true
)

Example:

Chronos.append_event(
  "player_1",
  "player_lied_to_guard",
  {"context":"conversation"},
  true
)

Chronos will automatically: store the world event → run the Brain → update NPC state → push the update back to the game.

Optional Call — Load saved NPC state on startup (recommended)

If a scene loads after a restart, you may want to fetch the current NPC state once.

Chronos.get_npc_state("guard_1")

This ensures the NPC immediately reflects the saved world state.

Advanced / debug calls

# Manual Brain run (debug / admin / testing)
Chronos.brain_think(50)

# Optional: set rules from game (advanced)
# Recommended MVP workflow: set rules in Vibe Console instead.
Chronos.set_rules("IF player_lied_to_guard THEN mood=hostile")

# Optional: read rules (debug)
Chronos.get_rules()

For MVP we recommend rules live in the Console so designers can tweak behavior without re-exporting the game.

Official Demo Reference

For a complete working integration example (Godot project, gameplay scripts, live event → Brain → state flow), review the official Demo 0.1v source code on GitHub.

View Demo Source on GitHub

This demo shows the best-practice MVP flow: append_event → auto Brain → npc_state_updated → gameplay reaction.

TROUBLESHOOTING

Common issues

• Plugin not showing? Confirm plugin.cfg and plugin.gd are inside res://addons/chronos/
• Requests failing? Ensure base_url starts with https:// and your API key is valid
• Live updates not arriving? Confirm Chronos.start() is running and SSE connects successfully
• State changes in Console but not in game? Confirm your game uses the same world_id and npc_id
• Need manual control? Use brain_think() for debug/admin only

Chronos Engine Docs — Beta. Keep feedback coming.