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/character |
Bounded skinned models, named animation tracks and shared clip banks |
format/worldreflection |
Saved cubemaps, projection volumes and explicit receiver bindings |
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/worldterrain |
Compiled heightfields, terrain ownership and resident mesh bounds |
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/textureatlas |
Build-time image pages, logical regions and filtered foliage mip chains |
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 world documents support versions 1–3, independently of their KWR1–KWR4
binary envelopes; 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.
Source and resource versions
Source versions retain the contracts of earlier documents. Optional resources use their own capability and binary versions; see each package's contract.
| Source | Addition | Resource capability |
|---|---|---|
| 13 | Per-room vegetation layers | world/vegetation@1 (KWV1) |
| 14 | Built-in shrub geometry | world/vegetation@2 (KWV2) |
| 15 | Optional vegetation normal textures | world/vegetation@3 (KWV3) |
| 16 | Tree geometry | world/vegetation@4 (KWV4) |
| 17 | Explicit liquid volumes | world/fluids@1 (KWR3) |
| 18 | Authored environment lighting and sky colors | world/environment@2 (KWR4) |
| 19 | Compact rectangular rooms | Existing compiled world contracts |
| 20 | Palm geometry | world/vegetation@5 (KWV5) |
Compiled terrain is an optional world/terrain@1 sidecar, independent of the
source document version. Its heightfield, local material palettes, normal maps
and sector floor ownership are defined in the terrain contract.
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.
Directories
¶
| 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
|
|
|
textureatlas
Package textureatlas filters build-time atlas mip chains.
|
Package textureatlas filters build-time atlas mip chains. |
|
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. |
|
character
Package character defines compiler-prepared skinned models and shared animation banks.
|
Package character defines compiler-prepared skinned models and shared animation banks. |
|
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. |
|
textureatlas
Package textureatlas defines immutable, build-time image atlases shared by sprites, UI, animation frames, vegetation and particles.
|
Package textureatlas defines immutable, build-time image atlases shared by sprites, UI, animation frames, vegetation and particles. |
|
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. |
|
worldreflection
Package worldreflection defines saved static parallax-corrected environments.
|
Package worldreflection defines saved static parallax-corrected environments. |
|
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. |