galaxy

Documentation

Overview

Package galaxy provides in-memory galaxy graph representation and pathfinding.

Index

• type Edge
• type GalaxyGraph
  • func (g *GalaxyGraph) BuildFromDB(ctx context.Context, kb knowledge.Base) error
  • func (g *GalaxyGraph) FindNearest(from string, targets []string, limit int) ([]NearestResult, error)
  • func (g *GalaxyGraph) FindPath(from, to string, weighted bool) (Route, error)
  • func (g *GalaxyGraph) Stats() GraphStats
• type GraphStats
• type NearestPOI
• type NearestResult
  • func FindNearestByPOIType(ctx context.Context, kb knowledge.Base, graph *GalaxyGraph, fromSystem string, ...) ([]NearestResult, error)
  • func FindNearestByResource(ctx context.Context, kb knowledge.Base, graph *GalaxyGraph, fromSystem string, ...) ([]NearestResult, error)
• type Position
• type Route
• type SystemNode

Types

type Edge

type Edge struct {
	To           string  `json:"to"`
	Distance     int     `json:"distance"` // jumps (always 1 for direct connections)
	FuelCost     float64 `json:"fuel_cost"`
	TravelTime   float64 `json:"travel_time"`
	LastTraveled string  `json:"last_traveled"`
}

Edge represents a connection between two systems.

type GalaxyGraph

type GalaxyGraph struct {
	// contains filtered or unexported fields
}

GalaxyGraph is an in-memory representation of the galaxy.

func (*GalaxyGraph) BuildFromDB

func (g *GalaxyGraph) BuildFromDB(ctx context.Context, kb knowledge.Base) error

BuildFromDB constructs the graph from the knowledge base. Queries systems, connections, and connection_metrics to build an adjacency list with metadata.

func (*GalaxyGraph) FindNearest

func (g *GalaxyGraph) FindNearest(from string, targets []string, limit int) ([]NearestResult, error)

FindNearest finds the closest systems from 'from' to any of 'targets'. Returns up to 'limit' results sorted by hop count (ascending).

func (*GalaxyGraph) FindPath

func (g *GalaxyGraph) FindPath(from, to string, weighted bool) (Route, error)

FindPath finds the shortest path between two systems using Dijkstra's algorithm. If weighted is true, uses fuel cost as the edge weight. If weighted is false, uses hop count (each edge has weight 1). Returns Route with the path, hop count, total fuel, and total travel time. Returns error if either system doesn't exist or no path exists.

func (*GalaxyGraph) Stats

func (g *GalaxyGraph) Stats() GraphStats

Stats returns graph statistics.

type GraphStats

type GraphStats struct {
	NodeCount int           `json:"node_count"`
	EdgeCount int           `json:"edge_count"`
	BuildTime time.Duration `json:"build_time"`
	BuiltAt   time.Time     `json:"built_at"`
}

GraphStats captures instrumentation data from graph building.

type NearestPOI

type NearestPOI struct {
	ID        string  `json:"id"`
	Name      string  `json:"name"`
	Remaining float64 `json:"remaining,omitempty"`
}

NearestPOI identifies one POI inside a NearestResult system that matched the query, with optional Remaining quantity for resource lookups.

type NearestResult

type NearestResult struct {
	SystemID   string `json:"system_id"`
	SystemName string `json:"system_name"`
	Hops       int    `json:"hops"`
	// Security is the numeric police level of the system; SecurityStatus is
	// the human-readable status string (e.g. "55 Medium", "0 Lawless").
	Security       int    `json:"security"`
	SecurityStatus string `json:"security_status"`
	LastUpdated    int64  `json:"last_updated"` // tick
	IsHomeBase     bool   `json:"is_home_base"`
	StaleWarning   string `json:"stale_warning"`
	// POIs lists the specific POIs within SystemID that satisfied the
	// query (e.g., the asteroid belts that hold a requested resource).
	// Populated for resource lookups; left nil for POI-type lookups.
	POIs []NearestPOI `json:"pois,omitempty"`
}

NearestResult is a candidate system with metadata for "nearest" queries.

func FindNearestByPOIType

func FindNearestByPOIType(
	ctx context.Context,
	kb knowledge.Base,
	graph *GalaxyGraph,
	fromSystem string,
	poiType string,
	limit int,
) ([]NearestResult, error)

FindNearestByPOIType returns up to `limit` nearest accessible systems that contain a POI of the given type, starting from `fromSystem`.

For poiType == "station", only systems with a publicly accessible station (PublicAccess == true) and not flagged IsStronghold are included. For any other poiType, any system containing a POI of that type is included.

Callers are expected to have already called graph.BuildFromDB.

func FindNearestByResource

func FindNearestByResource(
	ctx context.Context,
	kb knowledge.Base,
	graph *GalaxyGraph,
	fromSystem string,
	resourceID string,
	limit int,
) ([]NearestResult, error)

FindNearestByResource returns up to `limit` nearest accessible systems that contain at least one POI with a non-depleted entry for the given resource_id in the poi_resources table, starting from `fromSystem`.

Callers are expected to have already called graph.BuildFromDB.

type Position

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

Position represents 2D coordinates in space. This is distinct from game.Position which includes Z for 3D space - graph pathfinding only needs X/Y coordinates for distance calculations.

type Route

type Route struct {
	Path       []string `json:"path"`
	Hops       int      `json:"hops"`
	TotalFuel  float64  `json:"total_fuel"`
	TotalTicks int      `json:"total_ticks"`
}

Route is a path from one system to another.

type SystemNode

type SystemNode struct {
	ID             string   `json:"id"`
	Name           string   `json:"name"`
	Position       Position `json:"position"`
	Empire         string   `json:"empire"`
	IsStronghold   bool     `json:"is_stronghold"`
	PoliceLevel    int      `json:"police_level"`
	SecurityStatus string   `json:"security_status"`
	LastUpdated    int64    `json:"last_updated"` // game tick
}

SystemNode is a lightweight subset of game.SystemData for graph operations. Does not include POIs, online players, or discovery status.