Gates and Claims¶
Kanama's checks are scripts under scripts/. Most run as stages of
scripts/local_ci.sh and in CI; the device and browser runs are described in
Device and Browser Runs. The generated
Gates Index lists every stage and job, what
it proves and where it runs. This page covers running the local gate, the
rules every gate script follows, red runs, the checks that read the docs, the
checks behind the API conventions, and the source-break gate.
Local Validation¶
Run the local CI shortcut with one or more Godot binaries:
scripts/local_ci.sh /absolute/path/to/godot
With several binaries, the Godot stages run once per binary:
scripts/local_ci.sh \
/absolute/path/to/godot \
/absolute/path/to/godot
Before tagging a release, run the isolated source-and-demo gate from a clean temporary clone:
scripts/fresh_clone_smoke.sh /absolute/path/to/godot
For package validation, build the packaged artifacts (packaging needs the Android
SDK; see Release Process) and smoke them without a
sibling Kanama checkout. Add --android to a smoke to export an APK from the
package as well:
./gradlew packageDistributions
scripts/package_install_smoke.sh \
--desktop-kit \
build/distributions/kanama-desktop-kit-v<version>-<platform>.zip \
/absolute/path/to/godot
scripts/package_install_smoke.sh \
--store-addon \
build/distributions/kanama-store-addon-v<version>.zip \
/absolute/path/to/godot
local_ci.sh runs about forty stages (read the script for the list); the
headline ones are:
- API constant validation against
extension_api.json, - Gradle jar sync,
- native bootstrap configure/build when CMake is available,
- strict docs build when
mkdocsis available, - runtime smoke through
scripts/runtime_smoke.sh, @Tooleditor execution smoke,- editor probes, and
- hot-reload smoke.
runtime_smoke.sh checks the core Kanama runtime path: Godot loads the
GDExtension, starts the JVM, registers the script language and resource
loader, loads Kotlin scripts, and runs the example project far enough to verify
the expected markers.
editor_probe_smoke.sh checks the Kotlin edit loop the way a user meets it,
in a headless editor with the real Gradle build of the checkout. A scratch
project beside the checkout holds a @ScriptClass in a scene, and
scripts/check_editor_probes.gd runs as an editor plugin beside Kanama Tools.
It edits the .kt file and prints one PASS or FAIL line per probe:
- Build on save runs the real build and the status light ends green.
- The script Godot loaded for the file lists the new
@Exportproperty and method. - The node in the open scene has the new property, with its default, in its property list and in the inspector.
- A value set on the property survives saving and reloading the scene.
- A compile error turns the light red while the last good build keeps working, and the fix turns it green and runs.
- A class the editor registered at startup still loads a class it first
needs after builds replaced
kanama-scripts.jar.
It takes about 75 seconds and leaves no Gradle or Kotlin daemon behind, so it
runs in local_ci.sh (and so in CI on Linux) right after the @Tool smoke. An
interrupted run (Ctrl-C) stops the editor and its build. Run it alone with:
scripts/editor_probe_smoke.sh /absolute/path/to/godot
The Godot pin is kanamaGodotVersion in gradle.properties;
scripts/check_godot_version_pin.py fails local_ci.sh when a workflow or
build file drifts from it, and the Godot Upgrade Runbook is
the only process that moves it. With --release the same script fails unless
the pin is a stable Godot; the package workflow runs that first on every v*
tag. The JDK floor is the Gradle toolchain
(jvmToolchain(25) in build.gradle.kts). Gradle build cache is enabled for
the main Kanama build and the Android plugin build.
Install the docs dependencies with:
pip install -r docs/requirements.txt
Linux Validation¶
Use a Linux Godot binary of the pinned version and set
JAVA_HOME to JDK 25+:
cd /path/to/kanama-demos
JAVA_HOME=/path/to/jdk-25 \
XDG_DATA_HOME=/tmp/kanama-godot-state-linux \
XDG_CONFIG_HOME=/tmp/kanama-godot-config-linux \
KANAMA_DESKTOP_SMOKE_LOG_DIR=/tmp/kanama-desktop-smokes-linux \
scripts/desktop_smoke_all.sh /path/to/Godot_linux.arm64
desktop_smoke_all.sh defaults both XDG variables to those paths on Linux; set
them explicitly only to relocate the isolated state.
Use the Godot binary for the architecture under test, such as
Godot_v<version>_linux.arm64 or Godot_v<version>_linux.x86_64. The
demo smoke script uses Godot's OpenGL Compatibility renderer on desktop.
Before refreshing demo addons, rebuild the native bootstrap from a clean
checkout and preflight libkanama_bootstrap.so with file, ldd, and
readelf.
Windows Validation¶
Launch Godot from an environment with JAVA_HOME set to JDK 25+ so Kanama can
load %JAVA_HOME%\bin\server\jvm.dll, and use the pinned console
binary so smoke markers reach the terminal.
The native bootstrap needs CMake and MSVC, which are not on the default
PowerShell or Git Bash PATH: wrap every Gradle command that builds demos in
VsDevCmd.bat (a plain gradlew.bat buildAllScripts fails on the nested
native bootstrap otherwise):
cmd /c "call ""C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat"" -arch=x64 -host_arch=x64 && .\gradlew.bat buildAllScripts -PkanamaRoot=C:\path\to\kanama"
Point the demo builds at the Godot console binary either with the
KANAMA_GODOT environment variable or with -Pkanama.godot.executable=...
(the root aggregate tasks forward the property to nested demo builds):
cmd /c "call ""...\VsDevCmd.bat"" -arch=x64 -host_arch=x64 && .\gradlew.bat importAllGodot -PkanamaRoot=C:\path\to\kanama -Pkanama.godot.executable=C:\path\to\Godot_win64_console.exe"
Run the demo smoke matrix through Git Bash:
cmd /c "set KANAMA_DESKTOP_SMOKE_LOG_DIR=%TEMP%\kanama-desktop-smokes&& ""C:\Program Files\Git\bin\bash.exe"" scripts/desktop_smoke_all.sh C:\path\to\Godot_win64_console.exe"
The Gradle audit tasks resolve Python as py/python on Windows (the
python3 name usually hits the inert Microsoft Store shim). Keep
core.autocrlf disabled (the demo repos normalize to LF via
.gitattributes); CRLF-rewritten .tres/.tscn files fail Godot resource
parsing.
Gate Script Rules¶
A gate that swallows a failure is worse than no gate: it reports green for a
red state. Every gate script follows these rules, and
scripts/README-gates.md
holds the full text, the audit of the tree and the list of skip ids:
- A skip says so. A check that cannot run prints
SKIP: <id>: <reason>throughscripts/gate_skip.shorscripts/gate_skip.py. Under CI a skip fails unless its id is listed inKANAMA_ALLOW_SKIP. - No failure is swallowed. An
|| true,2>/dev/nullorcontinue-on-erroreither goes, or carries a# justified:comment that says why the verdict cannot change. - A path the gate reads must exist, and the set it scans must not be empty. A file that moved is a failure, not a pass.
- One portable path. A script CI can invoke runs on the tools a Mac and
the ubuntu runner both have;
scripts/check_script_portability.pyenforces the list. - A new gate ships with its red run (next section) and a row in
scripts/README-gates.md.
Red Runs¶
A red run shows a gate failing on a known-bad input. A gate seen only green is
a claim, not evidence. scripts/gate_red_runs.py holds one case(...) per
gate: the gate passes on the tree, fails with the expected text after a
reversible mutation, and passes again after the revert. Each case runs in a
throwaway git worktree of HEAD plus your uncommitted changes, so your
checkout is never mutated.
python3 scripts/gate_red_runs.py --list # the cases
python3 scripts/gate_red_runs.py --only doc # cases whose gate name contains "doc"
python3 scripts/gate_red_runs.py --strict # a skipped case fails (implied under CI)
python3 scripts/gate_red_runs.py --slow # also the Godot and Gradle smokes
python3 scripts/gate_red_runs.py --deadline-minutes 65 # stop in time and name the cases not run
Some cases edit exact sentences in the docs. When you change a page, grep the case list for its path and run those cases too.
Gates that need a device, a browser or a long export are not all in the
harness; they carry their own --self-test or recipe in
scripts/README-gates.md.
Checked Lines in the Docs¶
Some doc lines are read by scripts: the kanama-claim comments, the
KANAMA-BLOCKED comments, the iOS size and Kotlin version sentences in
reference/version-support.md, and the ./gradlew commands on the Get Started
pages. Writing These Docs lists them and
the checks to run before a docs change.
Doc claims. A doc line that states a fact kept elsewhere in the tree opts
into a check with an HTML kanama-claim comment on the same line.
scripts/check_doc_claims.py (in local_ci.sh and scripts/audit_claims.sh)
compares the stated value with its source: the protocol kind with the Web
bridge protocol in WebScriptCodeEmitter, the ios-static-size kind with the
measured sizes in reference/version-support.md. An unmarked mention is
history and is left alone, so a release never rewrites a correct "before
protocol N" sentence. The check fails on a marker whose kind it does not know,
and when no marker exists at all. A new kind needs an extractor in the script.
Stale-blocker markers. A comment that says a feature is blocked on X can
outlive X. A KANAMA-BLOCKED comment names the absence it depends on (a
symbol, a file, a Web call, an open task), and
scripts/audit_stale_blockers.py (a local_ci.sh stage) fails the build when
that absence is gone, so the comment goes red the day it becomes false. In a
.md file the marker is an HTML comment that travels with the paragraph it
guards. The grammar, with a live example, is "Documented Limitations" in the
repository's
CONTRIBUTING.md;
python3 scripts/audit_stale_blockers.py --list prints every marker.
Godot Upgrade Risks¶
Treat these as high-risk when moving to a new Godot version:
- GDExtension struct layouts.
- Script language and script instance virtual method surfaces.
- MethodBind and utility-function hashes.
- Builtin method hashes and constructor indexes.
VariantTypeenum ids.- Builtin type sizes such as Variant and GDExtensionCallError.
- Generated header function names such as
classdb_register_extension_class6. .gdextensioncompatibility metadata.- Engine singleton lifetime policy. Godot 4.7 preview builds warn when
Engine.register_singletonreceives aRefCounted; Kanama rejects this inEngine.registerSingletonand audits built-in singletons so singleton handles remain engine-ownedObjectinstances.
scripts/upgrade_godot.sh runs the generator gates as its last step; the runbook's rule is in
Godot Upgrade Runbook.
API Convention Checks¶
Each rule on API Conventions is held by
a check. "The drift gate" is scripts/check_wrapper_generator.py: the
committed tree is exactly what the generator writes, so every generated file,
including the enum prefix lock and the class-token tables, is held to the
generator.
| Rule | Kept by |
|---|---|
| 1. Names | The drift gate and the signature snapshot (Source Breaks). |
| 2. Properties | scripts/check_property_coverage.py (no Godot property on a generated class is dropped silently) and the drift gate. |
| 3. Integers | scripts/audit_wrapper_signatures.py and scripts/audit_wrapper_abi_policy.py --strict (each call's width matches Godot's), and the drift gate. |
| 4. Decimals | The value types' signatures in api-snapshots/types.txt / web-types.txt; the RealStorageWidthTest unit test (storage, equality, toString against Godot's strings, real_t arithmetic); the value_type_storage_smoke rows of scripts/runtime_smoke.sh, which compare an engine round trip, str(v), a few operations and a 256-input randomized parity row (every bit-identical operation, hashed per operation) with GDScript's in the same run; the builtin parity row, which compares every Kotlin-computed and engine-computed value-type member with GDScript over fixed-seed random inputs and over ±0, NaN, ±INF and .5 ties; and the Web WebValueTypeStorageTest (Node). |
| 5. Enums and Bitfields | scripts/check_typed_enums.py (native: no enum slot is a raw Long, names follow the lock, no top-level name shadows a Kotlin default import or a public Kanama type) and scripts/check_web_typed_enums.py (Web). scripts/runtime_smoke.sh compares each @Export* hint and hint string with its GDScript twin row by row. |
| 6. Nullability | scripts/check_typed_enums.py (part b: a required return is non-null and goes through requireGodotReturn, every other object return is nullable), scripts/check_web_typed_enums.py (the same on Web) and scripts/audit_generator_object_policy.py (the parameter decision and the override table). |
| 7. Ownership | The generator functions named in the rule; refcounted_ownership_problems in scripts/audit_generator_shape_policy.py, which checks every wrapper source for the owned or borrowed choice (returns and create() owned, fromHandle and typed-Array element callbacks borrowed) and that every returned object Array decodes through readArrayObjectsOwned; and scripts/runtime_smoke.sh, which asserts reference counts and liveness around the documented cases, and that 10,000 dropped owned Resources are released after a collection (with the fallback off, they stay). |
| 8. Statics and Singletons | The drift gate. |
| 9. Defaults and Overloads | scripts/check_expect_no_defaults.py (expect declarations), api_wrapper_generator_report.py --check (the "Godot Defaults Not Expressed" list) and the drift gate. |
| 10. Collections | scripts/audit_wrapper_signatures.py, scripts/audit_variant_marshalling_policy.py, scripts/type_coverage_audit.py, scripts/check_builtin_coverage.py (reads the standard library with javap and fails on a generated String method name that collides; --report lists every Godot method with its Kotlin member or the reason it has none) and the drift gate. |
| 11. Handles and Factories | check_factory_helpers, which every regeneration runs (the drift gate's included): a DOWNCAST_HELPERS key must be a class the generator renders, and no create() or downcast the generator renders may be pasted by hand into a section. The drift gate holds create() to generates_create (every instantiable Node and RefCounted). ClassTokenTableTest checks that the shared class-token table lists every shared class. |
| 13. Platform Parity | scripts/check_actual_public_surface.py keeps an actual from adding public members its expect lacks; check_public_signature_changes.py lists each Web GodotObject member that differs from native, with its reason (WEB_GODOT_OBJECT_DRIFT), and fails on any it does not list. |
Source Breaks¶
A source break is any change that can stop a script from compiling: a removed
or renamed member, class or parameter, a changed type or nullability, a removed
default argument, a member that is no longer open. Additions are not breaks,
and neither are the source-compatible changes the check recognises: a parameter
that gains a default, a declaration that becomes open, a class that gains a
supertype.
Before 1.0 a break is allowed when it serves the long-term shape of the API,
but never silently. Every break gets an entry in CHANGELOG.md under
## Unreleased that says what changed and how to migrate, with a line that
starts with the prefix below. The line may be indented, as a nested bullet, and
it names the owner of every declaration it breaks: the class or object
(Node, or Node.removeChild), or top-level for a top-level declaration; an
extension may name its receiver class instead. Names match as whole words, so
Node does not announce Node3D, and a qualified name announces that member
only: Node.removeChild does not announce Node.setProcessMode.
- **Source break:** `Node.removeChild` takes a nullable `Node?` ...
Keep a ## Unreleased section, even an empty one: with none, no break counts
as announced. The user-facing summary of this policy is the stability
paragraph on API Conventions.
scripts/check_public_signature_changes.py (a local_ci.sh stage) enforces
the policy: it compares the public surface with checked-in snapshots in the
repository's api-snapshots/ directory, one line per declaration, one file per
surface (every source directory is read recursively; a source can also be one file):
| Snapshot | Sources | What |
|---|---|---|
common.txt |
src/commonMain/.../api |
the shared native tree: generated classes, GlobalEnums.kt, the hand roots GodotObject, RefCounted, GodotCallable, GodotHandle, the expect declarations |
types.txt |
src/commonMain/.../types |
the builtin value types (Vector3, Color, Basis, ...) |
jvm.txt, ios.txt |
src/jvmMain/.../api, src/iosMain/.../api |
what each native platform declares on its own: the per-platform classes, the <Class>.jvm.kt / <Class>.ios.kt companions, the actuals, and on desktop the name constants (GD and Mathf are common) |
ios-seam.txt |
src/iosMain/.../ios/KanamaIosScriptSeam.kt |
the runtime declarations the generated iOS script registry calls. They are public behind the @InternalKanamaIosApi opt-in only because a kit project compiles that registry in its own build against the prebuilt runtime klib (see iOS Backend Architecture); game code never names them, so a removed or changed line there needs only --write, no CHANGELOG marker (the surface is internal) |
web.txt |
web-runtime/.../api |
the Web wrappers, generated and hand-written |
web-types.txt |
web-runtime/.../types |
the Web value types |
annotations.txt |
annotations/.../annotations |
the script annotations and their parameters (@ScriptClass, @Export, @Rpc, ...) |
A line records the owner, kind, name, receiver, type parameters and where
clauses, parameter names and types, whether each parameter has a default (not
the default's value), the return or property type, supertypes and source
modifiers (open, final, override, ...); annotations, constant values and
bodies are not part of it. Modifiers count whether they stand on the
declaration's own line or on the lines just above it. private and internal
declarations, and those marked @Deprecated(level = DeprecationLevel.HIDDEN),
are skipped, so hiding a declaration reads as removing it. The snapshots are
read from the Kotlin sources, not from a build, in a few seconds.
Every public declaration states its type. A declaration whose type is not
written out fails the gate with its file and line (fun seed(value: Long) = ...
must be fun seed(value: Long): Unit = ...), except where the type is certain
from the source: = Unit, a literal, a companion constant built with its own
class's constructor (val ZERO = Vector3(...)), or a Web import-compatibility
extension whose whole body calls the same-named member, whose type the gate
takes over. Today no declaration is left without a visible type.
The gate compares lines, so it also stops changes that still compile, such as a return that becomes non-null or a parameter that becomes nullable: those are announced the same way.
A new parameter with a default at the end of a function is source-compatible:
every call still compiles, so Godot's habit of adding one needs only --write.
Two cases stay breaks. An open function, because an override stops matching,
and a function whose last parameter was a lambda or a vararg, because a trailing
lambda or a spread stops reaching it.
| What changed | Gate result | What to do |
|---|---|---|
| nothing | PASS | — |
| signatures added, or a source-compatible change | FAIL: snapshots out of date | python3 scripts/check_public_signature_changes.py --write, commit the snapshots |
a signature removed or changed, its owner not named by a Source break line |
FAIL naming each change (was / now) and each unannounced owner |
fix the generator, or announce the break in the CHANGELOG |
| a signature removed or changed, its owner named | FAIL: snapshots out of date | --write, commit the snapshots with the change |
| a public declaration without a visible type | FAIL naming file and line | write the type |
--write refuses to record a removal or change whose owner no Source break
line names. The snapshot diff then shows every changed signature in the pull
request that changes it.