asset

Documentation

Overview

Package asset defines the Linefire vector asset model and its JSON representation. An asset describes the vector geometry and gameplay metadata (origin, hardpoints, collision) for a single object such as a ship, enemy, projectile or power-up.

Index

• Constants
• func Validate(a *Asset) error
• func ValidatePath(p Path) error
• type Asset
  • func New() *Asset
  • func (a *Asset) Clone() *Asset
  • func (a *Asset) DrawRadius() float64
  • func (a *Asset) Radius() float64
• type CollisionShape
• type Command
• type EditorSettings
• type Hardpoint
• type Layer
• type Path
  • func (p Path) Clone() Path
  • func (p Path) Closed() bool
  • func (p Path) Flatten() Path
• type Point
• type Size
• type Sound

Constants

const (
	OpMoveTo  = "M" // start a new sub-path at (X, Y)
	OpLineTo  = "L" // straight line to (X, Y)
	OpQuadTo  = "Q" // quadratic Bézier to (X, Y) with one control point (Ctrl[0])
	OpCubicTo = "C" // cubic Bézier to (X, Y) with two control points (Ctrl[0..1])
	OpClose   = "Z" // close the current sub-path
)

Path command operations.

const (
	KindWeapon   = "weapon"
	KindThruster = "thruster"
)

Hardpoint kinds.

const (
	CollisionCircle   = "circle"   // Points[0] = center, Radius set
	CollisionRect     = "rect"     // Points[0], Points[1] = opposite corners
	CollisionTriangle = "triangle" // Points[0..2] = vertices
)

Collision shape kinds.

const CurrentVersion = 2

CurrentVersion is the schema version written by this build. Older versions are migrated on load (see load.go); newer ones are refused.

const DefaultFileName = "linefire_asset.lfa"

DefaultFileName is where the asset editor saves when it was started without a path.

const DefaultRadius = 6

DefaultRadius is what an asset with no circle collision is treated as: small, so a shape nobody gave a hitbox is not accidentally enormous.

Functions

func Validate

func Validate(a *Asset) error

Validate checks structural and numeric invariants of an asset. It returns a descriptive error on the first problem found so callers can report it on the terminal instead of silently producing a broken file.

func ValidatePath

func ValidatePath(p Path) error

ValidatePath verifies a single path (shared by the asset and level checks): it must start with a move command and every command must use a known op with finite coordinates and, for curves, the right number of finite control points.

Types

type Asset

type Asset struct {
	Version    int
	Name       string
	Kind       string // spawn category: "enemy", "heal", "shield", "score", "ally", "neutral"
	Size       Size
	Origin     Point
	Layers     []Layer
	Hardpoints []Hardpoint
	Collisions []CollisionShape
	Sounds     []Sound // base sounds synthesized at load (gion)
	Editor     EditorSettings
	Tags       []string
}

Asset is the top-level document; filoio reads and writes it as Filo.

func New

func New() *Asset

New returns an empty asset with sensible defaults: a 64x64 box, a centered origin and a single empty "main" layer using the default neon style.

func (*Asset) Clone

func (a *Asset) Clone() *Asset

Clone returns a deep copy of the asset, independent of the original. It is used for editor history (undo/redo) and is safe to mutate.

func (*Asset) DrawRadius

func (a *Asset) DrawRadius() float64

DrawRadius is how far the drawn geometry actually reaches from the origin: the furthest point of any visible path, control points included.

It is not Radius. Radius is the HITBOX, which is deliberately generous — a power-up's is nearly twice the size of the icon on it so it is easy to fly into. Anything meant to hug what is DRAWN — a ring around a pickup, a highlight — wants this instead, or it sits far outside the shape it is supposed to be marking. Falls back to Radius when there is nothing drawn.

func (*Asset) Radius

func (a *Asset) Radius() float64

Radius is the asset's collision radius, taken from its first circle collision shape. It is what everything drawn around an asset should be sized from — a ring, a portal, a hit test — rather than from the art's box, which includes whatever margin the drawing needed.

type CollisionShape

type CollisionShape struct {
	Kind   string
	Points []Point
	Radius float64
}

CollisionShape is one hitbox primitive. The meaning of Points and Radius depends on Kind (see the collision kind constants).

type Command

type Command struct {
	Op   string
	X    float64
	Y    float64
	Ctrl []Point // curve control points (Q: 1, C: 2)
}

Command is a single drawing instruction inside a Path. (X, Y) is the endpoint; Ctrl holds the Bézier control points (one for OpQuadTo, two for OpCubicTo) and is empty otherwise. For OpClose the coordinates are unused.

type EditorSettings

type EditorSettings struct {
	SnapEnabled  bool
	SnapRadiusPx float64
	GridEnabled  bool
	GridSize     float64
	SnapToGrid   bool
}

EditorSettings persists editor preferences inside the asset file so a project reopens with the same snapping and grid behaviour.

type Hardpoint

type Hardpoint struct {
	Name  string
	Kind  string // KindWeapon or KindThruster
	X     float64
	Y     float64
	Angle float64 // degrees; 0 points right, -90 points up
}

Hardpoint marks a gameplay attachment point such as a gun muzzle or thruster.

type Layer

type Layer struct {
	Name        string
	Stroke      string  // hex color, e.g. "#80ffff"
	StrokeWidth float64 // in asset-space pixels
	Fill        string  // hex color or "transparent"
	Glow        float64 // reserved for the future game renderer
	Hidden      bool
	Paths       []Path
}

Layer groups paths that share the same stroke and fill style. Layers are drawn in slice order; later layers paint on top.

type Path

type Path struct {
	Commands []Command
}

Path is an ordered list of drawing commands forming one open or closed shape.

func (Path) Clone

func (p Path) Clone() Path

Clone returns a deep copy of the path, including each command's curve control points, so editors can snapshot it for undo without sharing mutable state.

func (Path) Closed

func (p Path) Closed() bool

Closed reports whether the path is explicitly closed (contains a close command). Open paths are stroked as polylines and are never filled, so simple lines render as lines rather than filled regions.

func (Path) Flatten

func (p Path) Flatten() Path

Flatten returns the path with every Bézier curve (Q/C) subdivided into line segments within flattenTol of the true curve, so consumers that only understand M/L/Z — the renderers, collision, bounds, the flood/fog geometry — need no curve handling. A path with no curves is returned unchanged (no allocation), so non-curved assets pay nothing.

type Point

type Point struct {
	X float64
	Y float64
}

Point is a 2D coordinate in asset space (pixels, origin at top-left).

type Size

type Size struct {
	W float64
	H float64
}

Size is the nominal bounding box of the asset in asset-space pixels.

type Sound

type Sound struct {
	Event      string
	Base       string
	Seed       int64
	Volume     float64
	Continuous bool
	Muted      bool
}

Sound is one base sound effect declared on an asset. The runtime synthesizes it (and several variations of it) at load with the gion library, so a repeated event does not sound identical, at zero asset cost. The asset stores only the recipe, never audio samples.

Event is the trigger name, by object type: a weapon's "fire", a power-up's "pickup", a ship's "destroy"/"thruster"/"hit", a special effect's "impact". Base names the base sound: a gion preset family ("laser", "explosion", "hit", "pickup", "powerup", "jump", "blip") or, in a future revision, an entry in an authored .gion document. Seed picks the base variation (0 = the preset default). Volume overrides the gain (0 = the preset's own). Continuous loops the sound while its state is active (an engine, a held laser) instead of playing once. Muted switches the sound off without deleting the entry (its tuning survives); a muted event is fully silent — it does not fall back to a default sound.