Hyperdot

Helps AI agents prove that a Godot game still works, in GDScript or C#.

Build, test, export and launch checks that answer in JSON an agent can read.
Runs on your Windows machine and, as a GitHub workflow, on Linux runners.

Self-test Godot Evals Licence: Apache-2.0 Godot 4.7.2 .NET 8 PowerShell 7.6+

Choose your path · Quick start · Features · Skills · Reference · Roadmap

An AI agent can write GDScript and C# and then say "done". Whether the game still builds, passes its tests, plays through its menus and starts after export is a different question, and an agent that answers it from memory is guessing.

Hyperdot makes it show evidence. One script detects the project, installs the right Godot, builds, runs every test framework the project uses, plays UI flows, exports and launches the build, and answers in JSON an agent can read. The agent is done when test -Json says ok: true, not when it says so. With the Claude Code plugin, a Stop hook pushes toward that: once for each set of changes it stops Claude from ending its turn while Godot files changed since the last full passing test run, and tells it to run the tests. If the tests ran and failed, or Claude stops again, it lets the turn end, so Claude must report the result. It checks only that; it does not judge the design or the code.

What the agent reads back when a test fails:

{ "schema": "hyperdot/1", "command": "test", "ok": false,
  "runnerResults": [
    { "runner": "gut", "ok": false, "total": 3, "passed": 2, "failed": 1,
      "failures": [ { "name": "test/test_score.gd.test_x", "message": "[20] expected to equal [25]:",
                      "file": "test/test_score.gd", "line": 7 } ] } ] }

Choose your path

Quick start

You need PowerShell 7.6+ and Git (Prerequisites); Godot is downloaded by the kit on the first run, and C# projects need the .NET 8 SDK.

Try it on the examples in this repository (a GDScript game with GUT, and a C# game with every framework):

git clone https://github.com/nick-vas/hyperdot
cd hyperdot
pwsh ci/godot/hyperdot.ps1 test -Project examples/gdscript -Json -Quiet
pwsh ci/godot/hyperdot.ps1 test -Project examples/csharp/game -Json -Quiet

Each prints one JSON result with "ok": true and a runnerResults entry per runner. detect -Project <game> shows what the kit found and changes nothing; doctor -Project <game> checks the machine and the project and gives a fix for each problem.

Use it on your game.

1. Clone the kit once, outside your game, and point it at the game with -Project. None of the kit's own code goes into your game's repository (init adds only the files listed below) or its exported builds:

   git clone https://github.com/nick-vas/hyperdot C:\Tools\hyperdot
   $kit = 'C:\Tools\hyperdot\ci\godot\hyperdot.ps1'
   $game = 'C:\path\to\your\game'
   pwsh $kit doctor -Project $game
   pwsh $kit init -Agents -Mcp godot-mcp -Project $game      # once: tests, CI, AGENTS.md, the plugin (skills, subagents, hooks), editor bridge
   pwsh $kit test -Json -Quiet -Project $game                # every time: build + every test, one JSON result
   

   ci/godot/tools/Initialize-HyperdotGame.ps1 -Game $game does these steps, finds a local Godot of your game's version before downloading anything, and makes a second working copy for a parallel Claude chat (docs/usage.md). init adds a starter test, a GitHub workflow, .gitignore lines, test exclusions in the export presets, AGENTS.md, CLAUDE.md, docs/kit-notes.md, the Claude Code plugin in .claude/settings.json (the skills, both subagents and the hooks come from it; nothing is copied into the game) and .mcp.json. It never overwrites a file and prints each change. The full list, and how to keep the kit in the game as a submodule instead: docs/usage.md.
2. If you only want the tests, you are done: use -Mcp and the steps below only with an agent.
3. With Claude Code the skills, subagents and hooks come from the plugin that init -Agents enabled in the game's .claude/settings.json; no skill is copied into the game (-CopySkills does that for a host without plugins). The plugin comes from this GitHub repository (-PluginSource github, the default; works in cloud sessions too; claude plugin update hyperdot@hyperdot fetches the newest commit on main) or from your clone (-PluginSource local: a git pull there updates every game). Skills are named /hyperdot:game, /hyperdot:kit and so on. Or by hand: /plugin marketplace add nick-vas/hyperdot, then /plugin install hyperdot@hyperdot.
4. If you chose -Mcp, run the addon command init prints and enable the plugin in Godot.
5. Open Claude Code in the game's folder and start every session with /game: it reads where the game stands (GDD, plan, tests, git), writes plan/STATUS.md and ends with the three best next tasks to pick from. Then ask the agent to work; it reads AGENTS.md and runs test -Json to check itself. /kit (or hyperdot.ps1 help) lists every command, skill and subagent in one line each; /kit <name> shows one page (docs/help.md).

Prerequisites

• PowerShell 7.6+ (winget install Microsoft.PowerShell) and Git.
• Godot: the kit downloads the version your project needs into ~/.hyperdot on the first run. Set GODOT_BIN to use your own.
• For C# projects, the .NET 8 SDK.

doctor checks a machine and a project and says what is missing.

What Hyperdot adds on top of your test framework

GUT, gdUnit4Net, GoDotTest and xUnit, NUnit or MSTest (through dotnet test) are the runners Hyperdot runs, not rivals: you keep writing your tests in them. They are test frameworks; the rows below are what Hyperdot puts around them.

What it gives an agent

Core is test, build and export, with detect and doctor to see what the kit found. That is all most games need, and it works with no editor bridge, no plan and no GitHub Project. Everything under Advanced is optional.

Understand the project

Test and verify

Ship

test picks its runners from the project: validate and architecture always; dotnet, godottest, gut, flows and smoke when their tests or a main scene exist; l10n when there are translations. The optional runners switch on when their file is in the project folder: juice.json, playthrough.json, data.json, textsize.json, layout.json, placement.json. -Runners picks them by hand. Every parameter: docs/reference.md.

Frameworks: GUT, gdUnit4Net, GoDotTest, xUnit/NUnit/MSTest via dotnet test, and UI flows. Verified on Godot 4.7.2 and .NET 8.

Advanced

Optional, and none of it is needed to run test, build or export: checks of the game itself, measurements, the plan and its GitHub Project mirror (experimental), the editor bridge, the skills, the two subagents and the Stop hook, and the benchmark and evals that measure the kit. The sections after the tables are How the pieces fit, Skills and The plan.

Check the game itself

Measure

Plan

Improve the agent and the kit

How the pieces fit

   plan -Json            what phase am I in, what is next
        |
   editor MCP            author and inspect: scenes, nodes, running game, live state   (needs the editor)
        |
   hyperdot.ps1 -Json    verify: build, test, flows, export, launch                     (headless, CI-safe)
   bench / shot          measure frame pacing, look at screens                          (with a display)
   audio [-Mix]          loudness of the sound files and of the game's own mix          (ffmpeg; -Mix needs a display)
        |
   plan -Do move/done    record progress; the GitHub Project mirrors the board

The editor is what you see; the files on disk are what CI and the export see. So the agent authors through the bridge, saves, and is done only when test -Json says ok: true. Neither editor MCP server builds C#, which is why the verification gate is a separate, headless tool.

Skills

53 skills in .agents/skills/. Each SKILL.md description says when to use it.

• Test and verify: godot-test-loop, verify-before-done, ui-flows, godot-diagnose, godot-pitfalls, automation-hooks, godot-editor-bridge, debug-tools
• Design and plan: game-plan, game-design, game-playtest, progression, narrative
• Code and systems: patterns, math, algorithms, procgen, game-ai, game-data, saves, input, xr, determinism, godot-addons, llm
• Look, sound and feel: game-juice, camera, animation, godot-shaders-vfx, asset-pipeline, game-audio, ui-accessibility, typography, localization, performance
• Online: multiplayer, servers, anti-cheat, game-telemetry, modding
• Ship: godot-export-release, release-readiness, mobile-web, steam, store-page, legal, console-cert
• Run by hand: game (where the game stands, what next), kit (every command, skill and subagent, one line each), look (style guide and screenshot critique), retro, kit-review, weekly-review

The godot-verifier subagent runs screenshots, benchmarks and export launches and returns a short verdict, so their logs and images stay out of the main conversation. The godot-architect subagent compares designs for a new system before code is written, records the decision in docs/decisions/ for you to accept, and keeps docs/ARCHITECTURE.md, the code's shape on one page (autoloads, scene tree, signals, authored and runtime data, save version, minimum spec, open questions).

The skills are checked like code: ci/godot/tools/Test-Skills.ps1 enforces structure and a 16 KB budget, and verifies that every command, flag, error code and package version a skill quotes exists. See docs/skills-quality.md.

The plan

Seven phases, each with gates: concept, prototype, vertical slice, production, alpha and beta, launch, post-launch.

A phase past its timebox warns you to cut scope, never testing. Tasks live in plan/plan.json and move through Backlog, Design, To Do, Doing, Verify and Done; move refuses to put a task in Doing past the work-in-progress limit. plan -Do sync -Board @me makes a private GitHub Project for the game and mirrors the tasks to it (experimental: tested against a stand-in gh only; needs the GitHub CLI signed in with the project scope). Where the plan comes from, and the project rules: docs/plan.md.

GitHub

on: [push, pull_request]
jobs:
  godot:
    permissions: { contents: read, pull-requests: write }
    uses: nick-vas/hyperdot/.github/workflows/godot.yml@v1

Tests on every push, a results comment on pull requests, optional coverage, exports and tagged releases. @v1 is a moving tag that follows the kit's releases, so a kit change reaches a game only when a release moves the tag, and a game moves up on purpose (docs/usage.md). In this repository, a weekly canary tries new Godot, test-framework and GUT releases on both examples and opens a pull request for those that pass. Free on public repositories; Linux runners are the cheapest on private ones. More: docs/usage.md and docs/reference.md.

Status

What has been run, and what has not.

FAQ

Documentation

Also as a website: nick-vas.github.io/hyperdot, the repository's default github.io address, built from these files on every change (docs/site.md).

Using the kit

• docs/usage.md: usage scenarios, from adding the kit to a game to several games in one repository
• docs/reference.md: parameters, config files, workflow inputs and secrets, cost
• docs/json.md: the -Json contract and error codes
• docs/coverage.md: which self-test covers each command, error code, kit file, tool, skill, subagent and workflow job, and the gaps
• docs/ci.md: what the kit's own CI runs when, what it costs, and which tests ever caught anything
• docs/ci-cache.md: a design for a CI cache keyed by the inputs of a job: stage 0 (hashes and markers, nothing skipped) is built; the rest awaits decisions
• docs/godot-pipelines.md: test frameworks, versions, release-safe packaging
• docs/self-hosted-runners.md: the workflow on your own machines
• docs/plan.md: the A-to-Z plan, tasks and GitHub Project sync
• docs/mcp.md: editor-bridge MCP servers and how they fit
• docs/roadmap.md: the plan to 0.1.0 and 1.0, decisions and the open to-do list
• docs/retro.md: a look back at the 0.1.0 effort: what went well, what cost time, numbers, lessons

Making the game

• docs/art.md: textures, pixel art, Blender to glTF, shaders, particles, animation
• docs/audio.md: buses, adaptive music, 3D sound, ducking, loudness targets
• docs/wcag-ui.md: WCAG 2.2 read as rules for game menus and UI
• docs/input.md: rebinding, controllers, button prompts, Steam Input
• docs/xr.md: OpenXR in Godot: the player's body, comfort, hands, throwing; what ran without a headset
• docs/localization.md: translations, plurals, fonts, the l10n runner
• docs/data.md: game data as Resources, JSON and CSV, the data runner
• docs/saves.md: save files that survive crashes, new versions and cloud conflicts
• docs/algorithms.md: textbook algorithms measured against Godot's built-ins
• docs/game-ai.md: state machines, behaviour trees, utility, steering, navigation
• docs/determinism.md: what .NET and Godot repeat, for replays and rollback
• docs/multiplayer.md: netcode, dedicated servers and soak
• docs/anti-cheat.md: server authority, trusted scores, client anti-cheat
• docs/telemetry.md: crash reports and analytics with consent
• docs/modding.md: PCK and ZIP mods, C# mods, Steam Workshop, mod.io
• docs/debug-tools.md: cheats, consoles and overlays that stay out of release builds
• docs/addons.md: popular add-ons and GDExtensions, and C# access to them
• docs/dialogue-tools.md: Dialogue Manager, Yarn Spinner, godot-ink, Dialogic and inkgd compared from their repositories
• docs/awesome-lists.md: what the kit took from awesome-godot and the awesome project, and what it left

Shipping

• docs/profiling-and-builds.md: C# profiling, GC, versions, signing, store uploads
• docs/mobile-web.md: Android and Web exports, touch, safe areas
• docs/steam.md: Steamworks bindings, Steam Deck, Cloud, achievements
• docs/console-cert.md: Xbox, PlayStation, Switch and Steam Deck certification
• docs/store-and-legal.md: store pages, ratings, privacy, licences and credits
• docs/publisher-contracts.md: two public publishing agreements, clause by clause

Research

• docs/research.md: output sizes, evals and the studies behind the plugin
• docs/token-benchmark.md: the token benchmark and how to read it
• docs/skills-quality.md: how the skills are checked, compared with other skill sets
• docs/case-study-breakout-roguelike.md: lessons from a real Godot 4.7 C# game
• docs/studio-lessons.md: what studios say worked and failed
• docs/valve.md: how Valve makes games, from its own public material
• docs/gdc/README.md: GDC talks and what the kit took from each
• docs/googleforgames.md: Google for Games' open source and what the kit took

This repository: AGENTS.md (working on it), docs/powershell.md (writing PowerShell here, with sources), CONTRIBUTING.md, SECURITY.md, CHANGELOG.md.

Licence

Hyperdot is licensed under the Apache License 2.0. Copies and modified versions must keep the NOTICE file, which credits Hyperdot and its author. The files Hyperdot copies into a game (ci/godot/templates/ and the starter tests init writes) are under MIT-0: a game owes nothing for them. Third-party parts keep their own licences, listed in NOTICE.

Innovating without patents Patent-free

The two banners above link to the End Software Patents campaign and are loaded from the campaign's host.

Hyperdot is not affiliated with or endorsed by the Godot Foundation. Godot and the Godot logo are trademarks of the Godot Foundation.