README
¶
Level envelopes and passive modules
Encode and Decode own the versioned, bounded KTYL level envelope.
WrapModule places a validated envelope in a canonical passive Wasm module,
with memory and the three level ABI exports. SDK 0.0.11 uses envelope/ABI
version 2 and rejects previous JSON metadata. Existing candidate KLDs require
rebuilding; released SDK hosts remain immutable.
ValidatePassiveModule rejects executable or noncanonical modules before a
consumer instantiates independently loaded child cartridges. Candidate SDK
0.0.11 also adds DecodePassiveModule: it performs the same validation and
returns the validated envelope without executing Wasm. Build caches can inspect
child metadata and payload contracts with this helper. Rejected modules never
expose an envelope, and errors retain ErrPassiveModule plus any underlying
envelope validation error.
Both passive helpers accept at most 32 MiB of module input containing at most 16 MiB of envelope data. The returned envelope borrows its raw, metadata and payload bytes from the module. Retain the module and treat it as immutable for the envelope's lifetime. Canonical reconstruction and the bounded entry table allocate during validation; no guest memory or instructions are executed.
These helpers validate the transport contract. Consumers must additionally validate mesh, lightmap and other named payload schemas against their parent level and catalog before publishing resources.
EncodeMetadata and DecodeMetadata own the bounded KTYM version 2 binary
object. Metadata values use explicit typed constructors and accessors; custom
metadata keys remain supported without reflection. Canonical keys are sorted,
unique, 1–1024 UTF-8 bytes. The entire record is scanned before allocation,
within 16 KiB, 2048 values and root-plus-16 nesting levels. Numbers are finite
and preserve signed/unsigned integer types. JSON and trailing bytes are rejected.
Binary metadata
EncodeMetadata and DecodeMetadata use typed Metadata objects and Value
constructors. Custom objects, arrays, booleans, strings, bytes, signed/unsigned
64-bit integers and finite 64-bit floats retain their types and precision.
There is no reflection, JSON parser or JSON compatibility fallback.
The header is KTYM, u16 version 2, u16 reserved zero. A tagged root object
follows: null 0, false 1, true 2, int64 3, uint64 4, float64 5, UTF-8 string 6,
bytes 7, object 8, array 9. Scalars are little-endian; strings/bytes have u32
lengths, objects/arrays have u32 counts. Objects encode sorted unique UTF-8 keys
as length-prefixed strings followed by their tagged values. Trailing bytes,
unknown tags, bad flags/versions and noncanonical keys are rejected.
Metadata has at most 16 KiB, 2048 values including its root, and depth 16 with
root depth zero. Keys contain 1–1024 UTF-8 bytes. Decoding scans the complete
payload and all nested bounds before allocating values. ValidateMetadata
performs this scan without allocating nested values. Authored YAML/TOML parsing
belongs to the CLI and is not a runtime dependency.
Documentation
¶
Overview ¶
Package level defines the bounded, versioned data envelope stored in a Karty level cartridge. It is shared contract code, not generated project output.
Index ¶
- Constants
- Variables
- func Encode(metadata []byte, source []SourceEntry) ([]byte, error)
- func EncodeMetadata(metadata Metadata) ([]byte, error)
- func TextureAssetID(name string) (uint32, bool)
- func TextureEntryName(assetID uint32) string
- func ValidateMetadata(encoded []byte) error
- func ValidatePassiveModule(wasm []byte) error
- func WrapModule(envelope []byte) ([]byte, error)
- type Entry
- type EntryKind
- type Envelope
- type Metadata
- type SourceEntry
- type Value
- func (v Value) AsArray() ([]Value, bool)
- func (v Value) AsBool() (bool, bool)
- func (v Value) AsBytes() ([]byte, bool)
- func (v Value) AsFloat() (float64, bool)
- func (v Value) AsInt() (int64, bool)
- func (v Value) AsObject() (Metadata, bool)
- func (v Value) AsString() (string, bool)
- func (v Value) AsUint() (uint64, bool)
- type ValueKind
Constants ¶
const ( EnvelopeVersion = uint16(2) HeaderSize = 32 EntryHeaderSize = 12 MaxEnvelopeSize = 16 * 1024 * 1024 MaxMetadataSize = 16 * 1024 MaxEntryCount = 4096 MaxEntryNameSize = 1024 MaxEntrySize = 8 * 1024 * 1024 )
const ( MetadataVersion = uint16(2) MaxMetadataDepth = 16 MaxMetadataNodes = 2048 MaxMetadataKeySize = 1024 )
const MaxPassiveModuleSize = 32 * 1024 * 1024
Variables ¶
var ( ErrEnvelopeSize = errors.New("level envelope size is invalid") ErrHeader = errors.New("level envelope header is invalid") ErrVersion = errors.New("level envelope version is unsupported") ErrMetadata = errors.New("level metadata is invalid") ErrEntry = errors.New("level data entry is invalid") ErrEntryOrder = errors.New("level data entries are not in canonical order") ErrEntryRange = errors.New("level data entry range is invalid") )
var ErrPassiveModule = errors.New("level module is not a canonical passive module")
Functions ¶
func Encode ¶
func Encode(metadata []byte, source []SourceEntry) ([]byte, error)
Encode creates a deterministic envelope. Entries are ordered by logical name; callers do not control table or payload order.
func EncodeMetadata ¶ added in v0.0.12
EncodeMetadata creates canonical binary metadata. Nil and empty objects have the same representation; JSON input is deliberately unsupported.
func TextureAssetID ¶
TextureAssetID recognizes a reserved texture payload name.
func TextureEntryName ¶
TextureEntryName returns the reserved envelope name for a nonzero, level-local texture ID.
func ValidateMetadata ¶ added in v0.0.12
ValidateMetadata checks the binary representation without allocating values.
func ValidatePassiveModule ¶ added in v0.0.12
ValidatePassiveModule accepts only exact WrapModule output. Run it before instantiating independently downloaded chunk modules: arbitrary Wasm imports, start functions, loops, memory growth or unbounded initial memories are never part of this data transport contract. Legacy level execution is unchanged. Validation allocates bounded canonical-module and data-construction buffers plus the envelope decoder's bounded entry table. It executes no instruction.
func WrapModule ¶
WrapModule places a validated KTYL envelope in a minimal passive core-Wasm module exposing the three level-cartridge ABI functions and memory.
Types ¶
type Envelope ¶
type Envelope struct {
Raw []byte
Metadata []byte
Entries []Entry
// contains filtered or unexported fields
}
Envelope is a validated view over immutable envelope bytes. Metadata and payload slices alias Raw and remain valid only while Raw is retained.
func DecodePassiveModule ¶ added in v0.0.12
DecodePassiveModule validates exact WrapModule output and decodes its level envelope without executing Wasm. The returned Raw, Metadata and payloads alias wasm, which the caller must retain and treat as immutable. It has the same input bounds, canonical ABI and errors as ValidatePassiveModule.
type Metadata ¶ added in v0.0.12
Metadata is a bounded, typed object. Its wire representation has sorted keys.
func DecodeMetadata ¶ added in v0.0.12
DecodeMetadata validates a complete payload before allocating nested values.
type SourceEntry ¶
SourceEntry is an authoring-time named payload passed to Encode. Texture entries must have distinct nonzero numeric IDs, even when logical names use different hexadecimal case.
type Value ¶ added in v0.0.12
type Value struct {
Kind ValueKind
Bool bool
Int int64
Uint uint64
Float float64
String string
Bytes []byte
Object Metadata
Array []Value
}
Value preserves custom metadata without runtime reflection or JSON parsing.
Source Files