worldsource

package
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: MIT Imports: 5 Imported by: 0

README

World authoring semantics

worldsource defines typed room, prefab, port, content and material authoring semantics. It has no YAML implementation dependency: tags describe field names, and Validate checks typed values. Public compilers own text parsing, presence and unknown-field checks, diagnostics, prefab expansion and convex decomposition. They must enforce compiled-world bounds again after expansion.

The Karty CLI generates local YAML editor schemas with karty schema. Run it from a game project to include that level's material, texture and prefab choices, or from this repository root to generate the shared base referenced by the standalone source fixture. The generated .karty/schemas directory is ignored; format validation and builds do not require the CLI or a YAML parser here.

Source version Added semantics
1 Rooms, prefabs and ordinary connections
2 Typed actors and instance tags
3 Directed and transformed connections
4 Root authored lighting
5 Material UV mapping
6 Static solids, root/prefab contents and room-free prefabs
7 Top/bottom wall bands and secondary colour textures

Versions 1–7 remain supported. Optional fields must respect their version gates; omitting new fields preserves older encodings. See the compiled world contract for output validation and lighting bounds. Root lighting remains in global coordinates and is never transformed by a prefab.

Material mapping, version 1

SDK 0.0.8 provides world/material-mapping@1. Authoring source v5 supports optional root uv, room floor_uv, ceiling_uv, wall_uv, and edge uv. Source v1–4 reject those fields; omission preserves their previous encodings and compiler behavior. Source v5 defaults to triplanar mapping with world anchoring, one world unit per repeat, zero offset and zero rotation. Controls inherit field by field from root to room to edge; nil numeric pointers and empty mode/anchor strings inherit. Explicit rotation_degrees: 0 overrides an inherited rotation.

mode accepts triplanar, planar, wrap; anchor accepts world, top, bottom. scale: {x: ..., y: ...} gives positive world units per repeat in [0.001, 1,000,000]. offset is in repeats, with finite components bounded to ±1,000,000. rotation_degrees is finite and bounded to ±1,000,000. Wrap and vertical top/bottom anchors apply to walls: top uses ceiling(x,y)-z, bottom uses z-floor(x,y). Explicit floor/ceiling wrap or top/bottom anchors are invalid. Inherited root wrap falls back to planar on floors/ceilings; inherited wall anchors do not move horizontal surfaces. The compiler resolves inheritance, projection axes, scale, offset, rotation, anchoring and prefab transforms.

See compiled mapping for the resolved affine projections and capability requirements.

Solids and loose contents, version 1

Source v6 adds optional solids and contents to root documents and prefabs. Detail-only, sprite-only and nested room-free prefabs expand into existing rooms without creating sectors. Older source versions reject these fields. Omission preserves existing encoded bytes. The source solid count is at most 1,024 across root solids and prefab definitions; compilers enforce it again after expansion.

Source material names resolve through packaged textures. Nested prefab scale, yaw, translation and material overrides apply to solids and loose sprites. The compiler assigns loose contents to the first containing compiled sector in stable order, including shared boundaries and elevation. Source caps inherit horizontal root mapping defaults; source side_uv is restricted to shared planar/world X/Z mapping. Per-edge wrap and varying side triplanar weights are not expressible by a single SideUV and are rejected. Mapped solids require the existing world/material-mapping@1 marker/capability; hosts also require world/static-solids@1. No new guest command or level envelope version is added.

See compiled solids for exact geometry, material and collision bounds.

Wall bands and secondary colour, source version 7

Source v7 adds wall_bands to rooms and bands to directed authored edges. Each contains optional enabled, top and bottom. Each horizontal band accepts texture, enabled, height, repeat_width and offset: {x, y}. Textures resolve through the ordinary level texture catalog; the same texture can be reused by both bands. Enabled resolved bands require a texture and height. Repeat width defaults to 1 world unit and offset to zero. Alpha is band coverage; transparent pixels reveal the underlying opaque wall.

Rooms also supply floor_secondary, ceiling_secondary, wall_secondary, and edges may override secondary. A secondary references one opaque texture, optional enabled, strength in [0,1], and existing uv settings. Its colour modulates the main in linear space; neutral sRGB (188,188,188) preserves the main colour. It does not replace normal, height or AO channels.

All optional fields inherit field by field after prefab expansion; explicit enabled: false disables an inherited setting. Builders apply material substitution independently to top, bottom and secondary references. MergeBandSettings returns independent nested band records, preserving input values. Dimensions and repeats use world units and must be finite in [0.001,1000000]; offsets retain ±1000000 bounds. Source versions 1–6 reject these fields; omission preserves their existing serialized shape. Typed SDK validation checks versions and partial controls; public text parsers must additionally reject explicit null and unknown fields and validate the complete resolved settings and resource references.

Horizontal bands follow visible solid-span floor and ceiling profiles with fixed vertical thickness. Opposing envelopes on a short span crop at a proportional boundary, retaining requested texture density. The builder compiles the complete nonoverlapping wall partition, mappings, material IDs and coverage classes. There are no vertical-band or frame-sheet authoring fields. The source-v7 simplification revises the unreleased SDK 0.0.10 candidate; released source versions and compiled world/material-layer formats are unchanged. See the compiled contract.

Documentation

Overview

Package worldsource defines the high-level, separately versioned room and prefab schema consumed by public world compilers. It intentionally has no YAML implementation dependency; tags describe the stable field vocabulary.

Index

Constants

View Source 
const (
	LegacyVersion        = uint16(1)
	ActorVersion         = uint16(2)
	PortalVersion        = uint16(3)
	LightingVersion      = uint16(4)
	MappingVersion       = uint16(5)
	SolidsVersion        = uint16(6)
	MaterialsVersion     = uint16(7)
	Version              = MaterialsVersion
	MaxRooms             = 1024
	MaxPrefabs           = 256
	MaxInstances         = 4096
	MaxConnections       = 8192
	MaxPorts             = 4096
	MaxEdges             = 8192
	MaxEdgesPerRoom      = 256
	MaxContents          = 4096
	MaxLights            = sdkworld.MaxLights
	MinLightRadius       = sdkworld.MinLightRadius
	MaxMaterialOverrides = 256
	MaxIdentifierBytes   = 128
	MaxTags              = 8
	MaxTagBytes          = 64
	MaxCoordinate        = 1_000_000.0
	MinEdgeLength        = 1e-6
	MinClearance         = 1e-6
)
View Source 
const MinUVScale = 0.001

Variables

View Source 
var (
	ErrVersion     = errors.New("world source version is unsupported")
	ErrBounds      = errors.New("world source exceeds a declared bound")
	ErrIdentity    = errors.New("world source identity is invalid")
	ErrGeometry    = errors.New("world source geometry is invalid")
	ErrReference   = errors.New("world source reference is invalid")
	ErrConnection  = errors.New("world source connection is invalid")
	ErrContent     = errors.New("world source content is invalid")
	ErrUVMapping   = errors.New("world source UV mapping is invalid")
	ErrLighting    = errors.New("world source lighting is invalid")
	ErrPrefabCycle = errors.New("world source prefab cycle is invalid")
)

Functions

func Validate 

func Validate(document *Document) error

Validate checks the complete source graph without expanding prefabs or decomposing rooms. Those compiler operations retain their own post-expansion bounds and diagnostics.

func ValidateBandSettings added in v0.0.10 

func ValidateBandSettings(b *BandSettings) error

func ValidateSecondarySettings added in v0.0.10 

func ValidateSecondarySettings(s *SecondarySettings) error

func ValidateUVSettings added in v0.0.8 

func ValidateUVSettings(settings *UVSettings) error

ValidateUVSettings checks typed authored controls without resolving inheritance.

Types

type Actor added in v0.0.6 

type Actor struct {
	YawDegrees   float64  `json:"yaw_degrees"      yaml:"yaw_degrees"`
	PitchDegrees float64  `json:"pitch_degrees"    yaml:"pitch_degrees"`
	RollDegrees  float64  `json:"roll_degrees"     yaml:"roll_degrees"`
	Scale        Vec3     `json:"scale"            yaml:"scale"`
	Sprite       *Sprite  `json:"sprite,omitempty" yaml:"sprite,omitempty"`
	Tags         []string `json:"tags,omitempty"   yaml:"tags,omitempty"`
}

type AmbientCube added in v0.0.8 

type AmbientCube struct {
	PositiveX Vec3 `json:"positive_x" yaml:"positive_x"`
	NegativeX Vec3 `json:"negative_x" yaml:"negative_x"`
	PositiveY Vec3 `json:"positive_y" yaml:"positive_y"`
	NegativeY Vec3 `json:"negative_y" yaml:"negative_y"`
	PositiveZ Vec3 `json:"positive_z" yaml:"positive_z"`
	NegativeZ Vec3 `json:"negative_z" yaml:"negative_z"`
}

AmbientCube supplies six world-space directional ambient colors. It replaces Ambient when present; squared unit-normal components weight each selected face. Colors are finite linear RGB intensities in [0,1].

type BandSettings added in v0.0.10 

type BandSettings struct {
	Enabled *bool                   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Top     *HorizontalBandSettings `json:"top,omitempty"     yaml:"top,omitempty"`
	Bottom  *HorizontalBandSettings `json:"bottom,omitempty"  yaml:"bottom,omitempty"`
}

BandSettings adds optional horizontal trim textures to visible wall spans. Builders resolve texture references, coverage and UVs before packaging.

func MergeBandSettings added in v0.0.10 

func MergeBandSettings(base, override *BandSettings) *BandSettings

MergeBandSettings applies non-omitted edge fields over a room default. The returned records are independent; nested pointer values remain immutable inputs.

type Connection 

type Connection struct {
	ID           string          `json:"id"                      yaml:"id"`
	A            Endpoint        `json:"a"                       yaml:"a"`
	B            Endpoint        `json:"b"                       yaml:"b"`
	Direction    PortalDirection `json:"direction,omitempty"     yaml:"direction,omitempty"`
	NonEuclidean bool            `json:"non_euclidean,omitempty" yaml:"non_euclidean,omitempty"`
}

Connection links two aperture endpoints. Direction defaults to both for compatibility. Each endpoint may own one outgoing link and may be the target of any number of links. NonEuclidean permits equal-length edges at different positions or orientations.

type Content 

type Content struct {
	ID       string `json:"id"              yaml:"id"`
	Kind     string `json:"kind"            yaml:"kind"`
	Position Vec3   `json:"position"        yaml:"position"`
	Actor    *Actor `json:"actor,omitempty" yaml:"actor,omitempty"`
}

type Document 

type Document struct {
	Version     uint16       `json:"version"     yaml:"version"`
	Rooms       []Room       `json:"rooms"       yaml:"rooms"`
	Prefabs     []Prefab     `json:"prefabs"     yaml:"prefabs"`
	Instances   []Instance   `json:"instances"   yaml:"instances"`
	Connections []Connection `json:"connections" yaml:"connections"`
	// Lighting is available in source v4 and later, in global world coordinates.
	// It is not part of any room, prefab or instance transform.
	Lighting *Lighting   `json:"lighting,omitempty" yaml:"lighting,omitempty"`
	UV       *UVSettings `json:"uv,omitempty"       yaml:"uv,omitempty"`
	Solids   []Solid     `json:"solids,omitempty"   yaml:"solids,omitempty"`
	Contents []Content   `json:"contents,omitempty" yaml:"contents,omitempty"`
}

type Edge 

type Edge struct {
	ID        string             `json:"id"                  yaml:"id"`
	Start     Vec2               `json:"start"               yaml:"start"`
	End       Vec2               `json:"end"                 yaml:"end"`
	Material  string             `json:"material"            yaml:"material"`
	UV        *UVSettings        `json:"uv,omitempty"        yaml:"uv,omitempty"`
	Bands     *BandSettings      `json:"bands,omitempty"     yaml:"bands,omitempty"`
	Secondary *SecondarySettings `json:"secondary,omitempty" yaml:"secondary,omitempty"`
}

Edge is one named, directed CCW boundary edge.

type Endpoint 

type Endpoint struct {
	Room     string `json:"room"     yaml:"room"`
	Edge     string `json:"edge"     yaml:"edge"`
	Instance string `json:"instance" yaml:"instance"`
	Port     string `json:"port"     yaml:"port"`
}

Endpoint selects either a room edge in the current scope or a named port on an instance in that scope. Exactly one pair must be populated.

type HorizontalBandSettings added in v0.0.10 

type HorizontalBandSettings struct {
	Enabled     *bool    `json:"enabled,omitempty"      yaml:"enabled,omitempty"`
	Texture     string   `json:"texture,omitempty"      yaml:"texture,omitempty"`
	Height      *float64 `json:"height,omitempty"       yaml:"height,omitempty"`
	RepeatWidth *float64 `json:"repeat_width,omitempty" yaml:"repeat_width,omitempty"`
	Offset      *Vec2    `json:"offset,omitempty"       yaml:"offset,omitempty"`
}

func MergeHorizontalBandSettings added in v0.0.10 

func MergeHorizontalBandSettings(base, override *HorizontalBandSettings) *HorizontalBandSettings

type Instance 

type Instance struct {
	ID        string             `json:"id"        yaml:"id"`
	Prefab    string             `json:"prefab"    yaml:"prefab"`
	Transform Transform          `json:"transform" yaml:"transform"`
	Materials []MaterialOverride `json:"materials" yaml:"materials"`
	// Tags replaces the actor tags of every content in this prefab instance.
	// An empty list preserves the prefab-authored tags.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
}

type LightMotion added in v0.0.8 

type LightMotion struct {
	Version       uint32  `json:"version"        yaml:"version"`
	Offset        Vec3    `json:"offset"         yaml:"offset"`
	PeriodSeconds float64 `json:"period_seconds" yaml:"period_seconds"`
}

LightMotion authors the bounded version-1 runtime light path.

type Lighting added in v0.0.8 

type Lighting struct {
	Version     uint32       `json:"version"                yaml:"version"`
	Ambient     Vec3         `json:"ambient"                yaml:"ambient"`
	Lights      []PointLight `json:"lights"                 yaml:"lights"`
	AmbientCube *AmbientCube `json:"ambient_cube,omitempty" yaml:"ambient_cube,omitempty"`
	Actors      bool         `json:"actors,omitempty"       yaml:"actors,omitempty"`
}

Lighting authors the world/lighting@1 payload. Version is the nested payload version (sdkworld.LightingVersion, 1), not the source document version. Ambient and Color use linear RGB intensities in [0,1]. Lights retain authored order and global positions; prefab-local lights are not supported.

type MaterialOverride 

type MaterialOverride struct {
	From string `json:"from" yaml:"from"`
	To   string `json:"to"   yaml:"to"`
}

type Plane 

type Plane struct {
	A float64 `json:"a" yaml:"a"`
	B float64 `json:"b" yaml:"b"`
	C float64 `json:"c" yaml:"c"`
}

Plane describes elevation z=A*x+B*y+C in source coordinates.

type PointLight added in v0.0.8 

type PointLight struct {
	ID       string       `json:"id"               yaml:"id"`
	Position Vec3         `json:"position"         yaml:"position"`
	Color    Vec3         `json:"color"            yaml:"color"`
	Radius   float64      `json:"radius"           yaml:"radius"`
	Motion   *LightMotion `json:"motion,omitempty" yaml:"motion,omitempty"`
}

PointLight has the same bounds and semantics as sdkworld.PointLight.

type Port 

type Port struct {
	ID       string   `json:"id"       yaml:"id"`
	Endpoint Endpoint `json:"endpoint" yaml:"endpoint"`
}

Port exposes one otherwise unconnected prefab endpoint to its instances.

type PortalDirection added in v0.0.7 

type PortalDirection string
const (
	PortalBoth PortalDirection = "both"
	PortalAToB PortalDirection = "a-to-b"
	PortalBToA PortalDirection = "b-to-a"
)

type Prefab 

type Prefab struct {
	ID          string       `json:"id"                 yaml:"id"`
	Rooms       []Room       `json:"rooms"              yaml:"rooms"`
	Instances   []Instance   `json:"instances"          yaml:"instances"`
	Connections []Connection `json:"connections"        yaml:"connections"`
	Ports       []Port       `json:"ports"              yaml:"ports"`
	Solids      []Solid      `json:"solids,omitempty"   yaml:"solids,omitempty"`
	Contents    []Content    `json:"contents,omitempty" yaml:"contents,omitempty"`
}

type Room 

type Room struct {
	ID               string             `json:"id"                          yaml:"id"`
	Boundary         []Edge             `json:"boundary"                    yaml:"boundary"`
	Floor            Plane              `json:"floor"                       yaml:"floor"`
	Ceiling          Plane              `json:"ceiling"                     yaml:"ceiling"`
	FloorMaterial    string             `json:"floor_material"              yaml:"floor_material"`
	CeilingMaterial  string             `json:"ceiling_material"            yaml:"ceiling_material"`
	Contents         []Content          `json:"contents"                    yaml:"contents"`
	FloorUV          *UVSettings        `json:"floor_uv,omitempty"          yaml:"floor_uv,omitempty"`
	CeilingUV        *UVSettings        `json:"ceiling_uv,omitempty"        yaml:"ceiling_uv,omitempty"`
	WallUV           *UVSettings        `json:"wall_uv,omitempty"           yaml:"wall_uv,omitempty"`
	WallBands        *BandSettings      `json:"wall_bands,omitempty"        yaml:"wall_bands,omitempty"`
	FloorSecondary   *SecondarySettings `json:"floor_secondary,omitempty"   yaml:"floor_secondary,omitempty"`
	CeilingSecondary *SecondarySettings `json:"ceiling_secondary,omitempty" yaml:"ceiling_secondary,omitempty"`
	WallSecondary    *SecondarySettings `json:"wall_secondary,omitempty"    yaml:"wall_secondary,omitempty"`
}

Room may be concave. The compiler decomposes it into convex sectors after prefab expansion and connection resolution.

type SecondarySettings added in v0.0.10 

type SecondarySettings struct {
	Enabled  *bool       `json:"enabled,omitempty"  yaml:"enabled,omitempty"`
	Texture  string      `json:"texture,omitempty"  yaml:"texture,omitempty"`
	Strength *float64    `json:"strength,omitempty" yaml:"strength,omitempty"`
	UV       *UVSettings `json:"uv,omitempty"       yaml:"uv,omitempty"`
}

SecondarySettings describes one colour-only detail image in source v7. Nil fields inherit room settings; Enabled=false disables the resolved layer.

type Solid added in v0.0.8 

type Solid struct {
	ID             string      `json:"id"                  yaml:"id"`
	Footprint      []Vec2      `json:"footprint"           yaml:"footprint"`
	Bottom         Plane       `json:"bottom"              yaml:"bottom"`
	Top            Plane       `json:"top"                 yaml:"top"`
	SideMaterial   string      `json:"side_material"       yaml:"side_material"`
	TopMaterial    string      `json:"top_material"        yaml:"top_material"`
	BottomMaterial string      `json:"bottom_material"     yaml:"bottom_material"`
	SideUV         *UVSettings `json:"side_uv,omitempty"   yaml:"side_uv,omitempty"`
	TopUV          *UVSettings `json:"top_uv,omitempty"    yaml:"top_uv,omitempty"`
	BottomUV       *UVSettings `json:"bottom_uv,omitempty" yaml:"bottom_uv,omitempty"`
	Collision      bool        `json:"collision,omitempty" yaml:"collision,omitempty"`
}

Solid is an extrusion independent of room decomposition. Root records use global coordinates; prefab records receive nested instance transforms. Optional UV controls inherit root horizontal defaults for caps; sides accept only an explicit planar/world mapping in version 6.

type Sprite added in v0.0.6 

type Sprite struct {
	Texture string  `json:"texture"  yaml:"texture"`
	Facing  string  `json:"facing"   yaml:"facing"`
	Alpha   string  `json:"alpha"    yaml:"alpha"`
	Width   float64 `json:"width"    yaml:"width"`
	Height  float64 `json:"height"   yaml:"height"`
	OriginX float64 `json:"origin_x" yaml:"origin_x"`
	OriginY float64 `json:"origin_y" yaml:"origin_y"`
}

type Transform 

type Transform struct {
	Translation Vec3    `json:"translation" yaml:"translation"`
	YawDegrees  float64 `json:"yaw_degrees" yaml:"yaw_degrees"`
	Scale       float64 `json:"scale"       yaml:"scale"`
}

Transform applies uniform scale, Z-axis yaw in degrees and translation. Scale zero means the schema default of one.

type UVAnchor added in v0.0.8 

type UVAnchor string
const (
	UVWorld  UVAnchor = "world"
	UVTop    UVAnchor = "top"
	UVBottom UVAnchor = "bottom"
)

type UVMode added in v0.0.8 

type UVMode string
const (
	UVTriplanar UVMode = "triplanar"
	UVPlanar    UVMode = "planar"
	UVWrap      UVMode = "wrap"
)

type UVSettings added in v0.0.8 

type UVSettings struct {
	Mode            UVMode   `json:"mode,omitempty"             yaml:"mode,omitempty"`
	Anchor          UVAnchor `json:"anchor,omitempty"           yaml:"anchor,omitempty"`
	Scale           *Vec2    `json:"scale,omitempty"            yaml:"scale,omitempty"`
	Offset          *Vec2    `json:"offset,omitempty"           yaml:"offset,omitempty"`
	RotationDegrees *float64 `json:"rotation_degrees,omitempty" yaml:"rotation_degrees,omitempty"`
}

UVSettings contains editor/compiler projection controls available in source v5. Empty Mode/Anchor and nil numeric fields inherit root -> room -> edge. Defaults are triplanar/world, scale (1,1), offset (0,0), rotation 0 degrees. Scale uses world units per repeat; Offset uses texture repeats. Rotation's pointer preserves an explicit zero override. Hosts receive only baked planes.

type Vec2 

type Vec2 struct {
	X float64 `json:"x" yaml:"x"`
	Y float64 `json:"y" yaml:"y"`
}

type Vec3 

type Vec3 struct {
	X float64 `json:"x" yaml:"x"`
	Y float64 `json:"y" yaml:"y"`
	Z float64 `json:"z" yaml:"z"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.