zeekayandGitHub 72aa2f1545 feat: local open-weight NPCs on zen6-nano (no key, no cloud) (#1)
- examples/local_npc.gd: an NPC voiced by zen6-nano via `hanzo load zen6-nano`.
- sdk_check: local mode (HANZO_BASE_URL on localhost) checks /v1/models, instruction
  following, and that the model identifies as Zen. 22/22 pass on dgx.
- CI: zen6-local serves zen6-nano on the runner CPU and runs the suite + example.
2026-11-10 22:59:16 -08:00

Hanzo — Godot 4 SDK

Built with Hanzo Edit on Hanzo

Official Godot 4 SDK (addons/hanzo_ai) for the Hanzo Cloud API at https://api.hanzo.ai — Docs · Agent Skill (godot.md).

Pure GDScript over Godot's built-in HTTPClient + TLSOptions.client() — zero GDExtension or .NET build required, works out of the box on Linux, macOS, Windows, Android, iOS, OpenXR/VR, and headless CI. Also compatible alongside the Hanzo NuGet package in Godot 4 .NET projects (see examples/csharp/).

Models & Game-Engine Surfaces

Capability Route Default Model Godot Return Shape
Dialogue, reasoning, code POST /v1/chat/completions zen6 (zen6-flash, zen6-coder, zen6-max) {ok, model, content, usage, latency_ms}
Tactical NPC / AI Director decisions POST /v1/decisions kai {ok, choice, confidence, probabilities, latency_ms}
Real-time 3D spatial voice synthesis POST /v1/audio/speech zen-voice {ok, bytes, audio_stream: AudioStreamMP3}
Public model discovery GET /v1/models — (security: []) {ok, count, models}
Key verification GET /v1/account/keys — {ok, keys}
Billing balance & usage GET /v1/billing/{balance,usage} — {ok, status, json}
Cloud KV game saves & state POST / PUT / GET / DELETE /v1/kv/{bucket}[/{key}] — {ok, data, revision, revisions}
Provisioning KV stores POST/GET/DELETE /v1/provisioning/kv — {ok, status, json}
Cloud Agents POST /v1/agent, POST /v1/agent/{ref}/run zen6-flash {ok, status, json}
MCP Tool catalog & JSON-RPC GET /v1/tool, POST /v1/mcp — {ok, count, tools} / {ok, result}

Install

Option 1: Copy or submodule addons/hanzo_ai

Download hanzo-godot-sdk-v1.1.0.zip from Releases (or clone hanzoai/godot-sdk) and copy addons/hanzo_ai/ into your Godot 4 project's addons/ folder, then enable Hanzo AI SDK under Project -> Project Settings -> Plugins.

Option 2: Godot 4 .NET (C#)

See examples/csharp/ to combine Godot 4 .NET with the Hanzo NuGet package (8.5.1026).

Authenticate

HanzoClient resolves credentials in one place from environment variables (or ProjectSettings under hanzo_ai/*):

Variable Meaning
HANZO_API_KEY Bearer credential: a Hanzo Cloud API key (hk-...) or IAM token
HANZO_BASE_URL Gateway origin; default https://api.hanzo.ai
HANZO_ORG_ID Optional org scope sent as X-Org-Id

Quickstart (GDScript)

var client := HanzoClient.from_env()

# 1. Zen 6 Dialogue / Narrative
var chat := client.chat_text("Give a one-line radio transmission from orbit.", "", "zen6")
print(chat["content"])

# 2. Kai Tactical NPC Decision (zero output tokens, ~100 ms)
var dec := client.decide_choice(
    {"health": 80, "ammo": 12, "target_visible": true},
    {
        "patrol": "continue route when area is clear",
        "engage": "attack visible threat when healthy",
        "retreat": "fall back when critically injured",
    }
)
print("NPC tactic: ", dec["choice"], " confidence=", dec["confidence"])

# 3. Zen Voice -> Playable Godot AudioStreamMP3
var voice := client.speech("Contact confirmed at sector four.", "alloy", "zen-voice")
if voice["ok"]:
    $AudioStreamPlayer3D.stream = voice["audio_stream"]
    $AudioStreamPlayer3D.play()

Non-Blocking 3D Node (HanzoAgent3D)

Drop HanzoAgent3D into any 3D/VR scene to run zen6, kai, and zen-voice on Godot's WorkerThreadPool without stalling frame pacing, emitting decision_ready, reply_ready, and speech_ready on the main thread and automatically playing spatial MP3 audio on a child AudioStreamPlayer3D.

Examples

All six canonical Hanzo SDK flows from hanzoai/openapi flows.yaml plus Godot-specific kai and speech flows:

Flow Script Route(s)
hello examples/hello.gd GET /v1/models, GET /v1/account/keys
chat examples/chat.gd POST /v1/chat/completions (zen6)
kai examples/kai.gd POST /v1/decisions (kai)
speech examples/speech.gd POST /v1/audio/speech (zen-voice -> AudioStreamMP3)
money examples/money.gd GET /v1/billing/balance, GET /v1/billing/usage
store examples/store.gd POST / GET / DELETE /v1/provisioning/kv
agent examples/agent.gd POST /v1/agent, POST /v1/agent/{ref}/run, DELETE /v1/agent/{ref}
tools examples/tools.gd GET /v1/tool
game_backend examples/game_backend.gd Complete game loop: Cloud KV saves -> Kai Director -> Zen 6 radio -> Zen Voice 3D MP3
csharp examples/csharp/HanzoGodotNode.cs Godot 4 .NET + Hanzo NuGet

Run any example headlessly with Godot 4.x:

HANZO_API_KEY=$(hanzo auth token) godot --headless --path . -s res://examples/game_backend.gd
HANZO_API_KEY=$(hanzo auth token) godot --headless --path . -s res://examples/hello.gd
HANZO_API_KEY=$(hanzo auth token) godot --headless --path . -s res://examples/chat.gd
HANZO_API_KEY=$(hanzo auth token) godot --headless --path . -s res://examples/kai.gd
HANZO_API_KEY=$(hanzo auth token) godot --headless --path . -s res://examples/speech.gd

The same API in other languages

Python · TypeScript · Go · Rust · C# · Java · C++ · all SDKs

License

Apache-2.0. See LICENSE.

Local open-weight models (no key, no cloud)

Run NPCs on an open-weight model on the player's or developer's machine:

hanzo load zen6-nano                      # Hanzo Engine on http://127.0.0.1:36900/v1
HANZO_BASE_URL=http://127.0.0.1:36900 HANZO_MODEL=zen6-nano \
  godot --headless --path . -s res://examples/local_npc.gd

HanzoClient talks to the local engine exactly as it talks to api.hanzo.ai; switch back by unsetting HANZO_BASE_URL. CI (.github/workflows/zen6-local.yml) serves zen6-nano (2B, 429 MB) on the runner CPU and runs tests/sdk_check.gd against it.

S
Description
Official Godot 4 SDK for the Hanzo Cloud API (api.hanzo.ai) — Zen 6 LLMs, Kai decisions, Zen Voice TTS, Agents, KV, Billing, and MCP Tools
Readme Apache-2.0
65 KiB
Languages
GDScript 100%