karty-sdk

module

v0.0.15 Latest Latest Go to latest Published: Oct 18, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/karty-game/karty-sdk

Links

Open Source Insights

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`	Authored sequences, action literals and level-scoped actor references
`format/world`	Canonical compiled convex-sector worlds, lighting, mapping and static solids
`format/worldvegetation`	Seeded per-sector vegetation layers, cutout presets and visibility bounds
`format/worldparticles`	Bounded GPU sprite particle presets, schedules and emitter motion envelopes
`format/worldsky`	Project-owned sky textures and bounded presentation settings
`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 mise, then run from this repository root:

mise install
mise run check-fmt
mise run test
mise run build

mise install installs pinned tools and the repository pre-commit hook. Use mise run fmt to apply formatting and mise run lint for the shared lint checks. See CONTRIBUTING for setup, codec regeneration, compatibility requirements and the race, SIMD fallback, 32-bit, Wasm, fuzz and benchmark checks.

Versions and releases

Go module tags (vVERSION) pin immutable public package dependencies. Engine artifact tags (sdk-vVERSION) version downloadable SDK bundles and hosts independently. Capability declarations govern host support separately from these release identifiers. Compiled worlds support versions 1–3, and authoring documents support versions 1–20. 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.

Source 14 adds built-in shrub geometry through vegetation version 2 (KWV2, world/vegetation@2); Source 13 / KWV1 remain supported.

Source 15 adds optional normal_texture vegetation resources through version 3 (KWV3, world/vegetation@3); earlier vegetation versions remain supported.

Source 16 adds geometry: tree through vegetation version 4 (KWV4, world/vegetation@4), retaining previous vegetation versions.

Source 17 adds explicit liquid volumes (world/fluids@1, KWR3), retaining KWR1/KWR2 worlds without fluid definitions.

Source 18 replaces prototype environment styles with explicit authored lighting and optional sky colors (world/environment@2, KWR4). Released environment inputs remain readable.

Compiled terrain is an optional world/terrain@1 sidecar. Its immutable heightfield, local four-material palettes, normal maps and sector floor ownership are defined in the terrain contract. Source version 18 remains unchanged.

Source 20 adds geometry: palm through vegetation version 5 (KWV5, world/vegetation@5), retaining all previous source and vegetation versions.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
authoring
actions Package actions exposes the editor schema only; it is not a runtime format.	Package actions exposes the editor schema only; it is not a runtime format.
bake
worldlightmap Package worldlightmapbake implements deterministic CPU direct and diffuse bounced RNM lightmaps.	Package worldlightmapbake implements deterministic CPU direct and diffuse bounced RNM lightmaps.
cmd
karty-actions-schema command karty-actions-schema exports the canonical public action schema into an SDK snapshot.	karty-actions-schema exports the canonical public action schema into an SDK snapshot.
codec
qoa Package qoa provides bounded one-shot and incremental adapters around Karty's pinned QOA codec.	Package qoa provides bounded one-shot and incremental adapters around Karty's pinned QOA codec.
qoi Package qoi provides a bounded adapter around Karty's pinned QOI codec.	Package qoi provides a bounded adapter around Karty's pinned QOI codec.
format
actions Package actions owns the bounded binary runtime action document format.	Package actions owns the bounded binary runtime action document format.
asset Package asset defines the public, versioned processing contract shared by Karty SDK manifests, the CLI asset processors, and runtime hosts.	Package asset defines the public, versioned processing contract shared by Karty SDK manifests, the CLI asset processors, and runtime hosts.
cartridge Package cartridge defines bounded data embedded in a Karty game cartridge.	Package cartridge defines bounded data embedded in a Karty game cartridge.
level Package level defines the bounded, versioned data envelope stored in a Karty level cartridge.	Package level defines the bounded, versioned data envelope stored in a Karty level cartridge.
performance Package performance owns the versioned cartridge contract for adaptive presentation profiles.	Package performance owns the versioned cartridge contract for adaptive presentation profiles.
world Code generated by internal/codegen/binary; DO NOT EDIT.	Code generated by internal/codegen/binary; DO NOT EDIT.
worldchunk Package worldchunk defines build-generated render assets and conservative streaming visibility for one logical world.	Package worldchunk defines build-generated render assets and conservative streaming visibility for one logical world.
worldlightmap Code generated by internal/codegen/binary; DO NOT EDIT.	Code generated by internal/codegen/binary; DO NOT EDIT.
worldmaterial Package worldmaterial defines the build-time world material atlas contract.	Package worldmaterial defines the build-time world material atlas contract.
worldparticles Code generated by internal/codegen/binary; DO NOT EDIT.	Code generated by internal/codegen/binary; DO NOT EDIT.
worldsky Package worldsky defines project-owned, bounded skydome textures and presentation.	Package worldsky defines project-owned, bounded skydome textures and presentation.
worldsource Package worldsource defines the high-level, separately versioned room and prefab schema consumed by public world compilers.	Package worldsource defines the high-level, separately versioned room and prefab schema consumed by public world compilers.
worldterrain Package worldterrain defines compiled, immutable heightfield ground resources.	Package worldterrain defines compiled, immutable heightfield ground resources.
worldvegetation Code generated by internal/codegen/binary; DO NOT EDIT.	Code generated by internal/codegen/binary; DO NOT EDIT.
internal
binwire Package binwire implements bounded, canonical primitives for generated typed format codecs.	Package binwire implements bounded, canonical primitives for generated typed format codecs.
cleanup Package cleanup provides best-effort release after a primary operation.	Package cleanup provides best-effort release after a primary operation.
codegen/binary command Command binary emits static typed field codecs from the public Go contracts.	Command binary emits static typed field codecs from the public Go contracts.