worldsource

package
v0.0.8 Latest Latest
Warning

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

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

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)
	Version              = SolidsVersion
	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 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 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"`
}

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 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"`
}

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

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.