karty-sdk

README

Karty SDK

The public contracts shared by the Karty CLI, public compilers and game engine. This Go module builds independently of engine source and credentials.

Package	Responsibility
format/cartridge	Game manifests, embedded assets, Wasm sections and streaming media catalogs
format/level	Versioned level envelopes and modules
format/worldchunk	Independent render chunks, offline meshes and conservative streaming visibility
format/actions	Candidate authored sequences, action literals and level-scoped actor references
format/world	Canonical compiled convex-sector worlds, lighting, mapping and static solids
format/worldparticles	Bounded GPU sprite particle presets, schedules and emitter motion envelopes
format/worldsource	Separately versioned room, prefab, port and content authoring semantics
format/worldmaterial	Material atlases, mip tails and strength controls
format/worldlightmap	Static receiver charts, bake recipes and completed prebake formats
bake/worldlightmap	Deterministic CPU direct/diffuse RNM baking
format/performance	Binary adaptive presentation profiles
codec/qoi, codec/qoa	Bounded adapters around pinned image and audio codecs

The SDK owns formats and shared validation. Public compilers own authoring parsing and expansion; the CLI owns project building and asset processing; the engine owns runtime execution and graphics. Published package paths remain stable. Detailed contracts live beside their owning packages.

Development

Install the pinned tools with mise, then run from this repository root:

mise install
mise run fmt
mise run check-fmt
mise run lint
mise run test
mise run build
mise run test-race
mise run test-simd-emulated
mise run test-32
mise run test-wasm
mise run fuzz
mise run bench

The shared checks in hk.pkl use golangci-lint for Go (including govet), yamllint for YAML, Taplo for TOML, and Prettier for YAML layout, JSON, Markdown and web files. Taplo validates syntax without downloading schemas.

mise install installs the pinned tools and repository pre-commit hook through mise; use mise run install-hooks to reinstall it. The hook checks staged files and applies formatting fixes while preserving unstaged work. fmt applies all formatters through hk without staging; check-fmt reports differences without writing files. lint runs all format and lint checks; check also runs tests and build. Generated Go and *.generated.* snapshots, derived output and local contributor directories and binary fixtures are excluded from formatting. Authoring YAML fixtures retain their decoder input format; yamllint checks them.

After changing typed world/lightmap/material declarations, regenerate their checked-in codecs with mise exec -- go generate ./format/world. Runtime formats use bounded typed binary; tests reject JSON/reflection imports in format and codec production code. The candidate binary wire replaces released JSON artifacts and requires rebuilding levels and bake caches.

After changing authoring/actions/schema.json, regenerate consumer snapshots with their mise run generate-action-contract tasks; public SDK checks remain independent of private source.

The pinned mise environment enables Go 1.27 portable SIMD for the offline baker. Direct Go builds importing that package require GOEXPERIMENT=simd; format-only imports are unaffected. test-simd-emulated exercises Go's built-in fallback rather than a second production implementation.

test-race runs one package at a time to bound instrumentation overhead. Dense baker producer compatibility fixtures run in a separate process with the same nine-second timeout; both invocations retain race detection. test-32 executes native 386 tests on an x86 Linux host with 32-bit execution support. fuzz verifies each configured target exists before exploring it for a bounded budget; normal tests also run the seed corpus. test-wasm executes Go Wasm tests using the official Go runner and pinned Node, running one package at a time to bound memory use. Its launcher passes a minimal environment to stay within Go's 8 KiB argument/environment limit, preserving temporary paths and the GODEBUG and GOMAXPROCS runtime controls. It does not exercise browser graphics. Benchmarks report allocation totals and CPU time for fixed codec, material-atlas, connected-world and bake fixtures. See CONTRIBUTING for compatibility and review requirements.

Versions and releases

Go module tags (vVERSION) pin immutable public package dependencies. Engine artifact tags (sdk-vVERSION) version downloadable SDK bundles and hosts independently. SDK 0.0.8 contracts are documented as available features, rather than unfinished proposals; capability declarations still govern host support. Compiled worlds support versions 1–3, and authoring documents support versions 1–10. New optional features retain their explicit version gates and canonical encoding rules. Incompatible formats or producer behavior need a versioned decision and compatibility coverage.

The private engine workflow publishes SDK bundles, native hosts, browser Wasm, checksums and signatures here. This repository does not build private engine source. Game developers obtain these artifacts through Karty, without engine access or credentials.

Licensing

The MIT license covers this repository's source, exported SDK bindings and templates. The pinned codec dependencies have their own MIT notices in codec/qoi and codec/qoa. Official runtime binaries use the separate Karty Runtime License, which allows distribution with free and commercial games; private engine implementation source remains proprietary.