SDK Install

Recommended workflow: set World Rules in Vibe Console (not in game code), then your game only sends events and reads NPC state.

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",   # generate from Vibe Console
    "game_id",         # example: "village_reputation"
    "npc_id"           # example: "guard_1"
  )

  Chronos.start() # starts SSE stream (optional but recommended)

  Chronos.connect("request_ok", self, "_on_ok")
  Chronos.connect("request_err", self, "_on_err")

  print("SETUP: Chronos configured + started")

func _on_ok(tag, _data):
  print("[Chronos OK]", tag)

func _on_err(tag, code, message, _raw):
  print("[Chronos ERR]", tag, code, message)

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

STEP 04

Call the SDK in your game code

This is the core MVP flow: your game sends events → Brain updates state → your game reads NPC state.
Recommended: do NOT set World Rules inside game code. Set rules in Vibe Console so you can change behavior anytime without touching code (especially important when you later have many NPCs).

Must-use SDK calls (MVP)

These are the minimum calls you need in gameplay.

# 1) Append a gameplay event (writes to world_events)
Chronos.append_event(
  "player_1",             # entity_id (who did it)
   event_type,            # event_type (what happened)
   payload,               # payload (details)
	 true                 # significant (used for quota + importance)
)

# 2) Trigger the Brain (writes npc_decision + updates npc_states)
Chronos.brain_think(50)

# 3) Fetch the latest NPC state (reads npc_states)
Chronos.get_npc_state("guard_1")

Why this matters: append_event stores memory, brain_think converts memory into state, get_npc_state lets your game react instantly.

Optional calls (advanced)

# Optional: set rules from game (NOT recommended for MVP)
# Better: set rules in Vibe Console (editable anytime).
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 NPC behavior without re-exporting the game.

Official Demo Reference

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

View Demo Source on GitHub

This demo shows best-practice SDK usage, including: append_event → brain_think → get_npc_state → 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
• NPC state always empty? Make sure you call Chronos.brain_think() after events
• State changes in Console but not in game? Confirm your game uses the same world_id and npc_id

Chronos Engine Docs — Beta. Keep feedback coming.