save

Documentation

Overview

Package save persists and restores the simulation World as JSON.

The on-disk envelope ships a richer header from day one — version, generator, clock_t0, body_catalog_hash, payload — so future schema migrations and the v0.6 multiplayer `session` block can land without bumping every caller. See docs/state-of-game.md §3 v0.4.0 for the rationale.

Index

• Constants
• Variables
• func DefaultPath() (string, error)
• func Load(path string) (*sim.World, error)
• func Save(w *sim.World, path string) error
• type ActiveBurn
• type Craft
• type File
• type Focus
• type Node
• type Payload
• type Vec3

Constants

const SchemaVersion = 1

SchemaVersion is the on-disk version. v0.4.0 ships v1; later schema changes bump and migrate.

Variables

var (
	ErrSchemaMismatch  = errors.New("save: schema version mismatch")
	ErrCatalogMismatch = errors.New("save: body catalog hash mismatch")
	ErrCraftPrimary    = errors.New("save: craft primary not found in loaded systems")
)

Errors returned by Load.

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the platform-appropriate save path. Honors $XDG_STATE_HOME on linux/macOS; falls back to ~/.local/state. Windows users can set $XDG_STATE_HOME explicitly.

func Load

func Load(path string) (*sim.World, error)

Load reads path, validates the envelope, and returns a fresh World hydrated from the payload. Errors with ErrSchemaMismatch on version drift, ErrCatalogMismatch on body-catalog drift, or ErrCraftPrimary when the craft references a primary that no longer exists.

func Save

func Save(w *sim.World, path string) error

Save serialises w to path, creating parent directories as needed. Atomic on POSIX: writes to a sibling tmpfile and renames into place.

Types

type ActiveBurn

type ActiveBurn struct {
	Mode        int     `json:"mode"`
	DVRemaining float64 `json:"dv_remaining"`
	EndTimeNano int64   `json:"end_time_unix_nano"`
	PrimaryID   string  `json:"primary_id"`
}

ActiveBurn mirrors sim.ActiveBurn.

type Craft

type Craft struct {
	Name      string  `json:"name"`
	DryMass   float64 `json:"dry_mass"`
	Fuel      float64 `json:"fuel"`
	Isp       float64 `json:"isp"`
	Thrust    float64 `json:"thrust"`
	PrimaryID string  `json:"primary_id"`
	R         Vec3    `json:"r"`
	V         Vec3    `json:"v"`
	M         float64 `json:"m"`
}

Craft mirrors spacecraft.Spacecraft. Primary is referenced by ID; the rehydrated value is looked up across loaded systems on Load.

type File

type File struct {
	Version         int     `json:"version"`
	Generator       string  `json:"generator"`
	ClockT0         int64   `json:"clock_t0"`
	BodyCatalogHash string  `json:"body_catalog_hash"`
	Payload         Payload `json:"payload"`
}

File is the on-disk envelope.

type Focus

type Focus struct {
	Kind    int `json:"kind"`
	BodyIdx int `json:"body_idx"`
}

Focus mirrors sim.Focus by value.

type Node

type Node struct {
	TriggerTimeNano int64   `json:"trigger_time_unix_nano"`
	Mode            int     `json:"mode"`
	DV              float64 `json:"dv"`
	DurationNano    int64   `json:"duration_nano"`
	PrimaryID       string  `json:"primary_id"`
}

Node mirrors sim.ManeuverNode.

type Payload

type Payload struct {
	SystemIdx    int         `json:"system_idx"`
	SimTimeNano  int64       `json:"sim_time_unix_nano"`
	BaseStepNano int64       `json:"base_step_nano"`
	WarpIdx      int         `json:"warp_idx"`
	Paused       bool        `json:"paused"`
	Focus        Focus       `json:"focus"`
	Craft        *Craft      `json:"craft,omitempty"`
	Nodes        []Node      `json:"nodes,omitempty"`
	ActiveBurn   *ActiveBurn `json:"active_burn,omitempty"`
}

Payload carries the live simulation state. Anything derivable from the catalog (Systems, Calculator) is reconstructed on Load.

type Vec3

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

Vec3 is the wire form of orbital.Vec3.