Struct GalaxyModel 

pub struct GalaxyModel {
    pub graph: StableGraph<SystemId, f64, Undirected>,
    pub spatial: HashMap<u8, RTree<SystemPoint>>,
    pub active_galaxy: u8,
    pub systems: HashMap<SystemId, System>,
    pub planets: HashMap<PlanetKey, Planet>,
    pub bases: HashMap<String, PlayerBase>,
    pub biome_index: HashMap<Biome, Vec<PlanetKey>>,
    pub name_index: HashMap<String, SystemId>,
    pub address_to_id: HashMap<u64, SystemId>,
    pub node_map: HashMap<SystemId, NodeIndex>,
    pub player_state: Option<PlayerState>,
}

The in-memory galactic model.

Three parallel data structures kept in sync:

1. petgraph – topology (pathfinding, routing)
2. R-tree – spatial (nearest-neighbor, radius queries)
3. HashMaps – associative (name, biome, address lookups)

Fields

graph: StableGraph<SystemId, f64, Undirected>

Graph topology: nodes are systems, edge weights are distance in ly.

spatial: HashMap<u8, RTree<SystemPoint>>

Per-galaxy 3D spatial indexes of system positions.

active_galaxy: u8

Currently active galaxy for spatial queries.

systems: HashMap<SystemId, System>

System data by ID.

planets: HashMap<PlanetKey, Planet>

Planet data by (SystemId, planet_index).

bases: HashMap<String, PlayerBase>

Base lookup by name (lowercase).

biome_index: HashMap<Biome, Vec<PlanetKey>>

Biome -> list of planets with that biome.

name_index: HashMap<String, SystemId>

System name -> SystemId (lowercase, only for named systems).

address_to_id: HashMap<u64, SystemId>

Packed address (planet bits zeroed) -> SystemId.

node_map: HashMap<SystemId, NodeIndex>

SystemId -> petgraph NodeIndex.

player_state: Option<PlayerState>

Current player state (position, currencies).

Implementations

impl GalaxyModel

pub fn build_edges(&mut self, strategy: EdgeStrategy)

Build edges using the given strategy. Clears existing edges first.

pub fn connect_new_system(&mut self, sys_id: SystemId, k: usize)

Add KNN edges for a single newly inserted system.

Call this after insert_system() to connect the new node to its neighbors without rebuilding the entire graph. Looks up the system’s galaxy to use the correct spatial index.

impl GalaxyModel

pub fn new() -> Self

Create an empty GalaxyModel.

pub fn from_save(save: &SaveRoot) -> Self

Build a GalaxyModel from a parsed save file.

pub fn system_count(&self) -> usize

Number of systems in the model.

pub fn planet_count(&self) -> usize

Number of planets in the model.

pub fn base_count(&self) -> usize

Number of bases in the model.

pub fn system(&self, id: &SystemId) -> Option<&System>

Look up a system by its ID.

pub fn system_by_name(&self, name: &str) -> Option<(&SystemId, &System)>

Look up a system by name (case-insensitive).

pub fn base(&self, name: &str) -> Option<&PlayerBase>

Look up a base by name (case-insensitive).

pub fn player_position(&self) -> Option<&GalacticAddress>

Get the player’s current position, if available.

pub fn active_spatial(&self) -> Option<&RTree<SystemPoint>>

Get the spatial index for the active galaxy.

pub fn spatial_for(&self, galaxy: u8) -> Option<&RTree<SystemPoint>>

Get the spatial index for a specific galaxy.

pub fn set_active_galaxy(&mut self, galaxy: u8)

Switch the active galaxy.

pub fn discovered_galaxies(&self) -> Vec<u8>

List galaxies that have at least one discovered system.

pub fn rebuild_spatial(&mut self)

Rebuild all per-galaxy R-trees from the systems HashMap.

pub fn spatial_size(&self) -> usize

Total number of points across all per-galaxy spatial indexes.

pub fn planets_by_biome(&self, biome: Biome) -> Vec<&Planet>

Get all planets with a given biome.

pub fn insert_system(&mut self, system: System)

Insert a new system into all indexes.

pub fn ensure_player_system(&mut self)

Ensure the player’s current system exists in the model.

If the player’s system has no discovery record, this inserts a placeholder system at the player’s address so that distance queries correctly return 0.0 for in-system results.

pub fn insert_base(&mut self, base: PlayerBase)

Insert a base into the model.

pub fn apply_delta(&mut self, delta: &SaveDelta)

Apply a delta from the file watcher to update the model incrementally.

Inserts new systems and planets, updates player position, and adds/updates bases. Does NOT rebuild graph edges – call build_edges() afterward if needed for routing.

impl GalaxyModel

pub fn resolve_position( &self, address: Option<&GalacticAddress>, base_name: Option<&str>, ) -> Result<GalacticAddress, GraphError>

Resolve a reference point to a GalacticAddress.

Accepts:

• A direct address (returned as-is)
• A base name (looked up in the base index)
• None for both (uses player position)

pub fn nearest_systems( &self, from: &GalacticAddress, n: usize, ) -> Vec<(SystemId, f64)>

Find the N nearest systems to a reference point.

Uses the active galaxy’s spatial index. Returns empty if the active galaxy has no systems.

Returns (SystemId, distance_in_ly) pairs sorted by distance ascending.

pub fn systems_within_radius( &self, from: &GalacticAddress, radius_ly: f64, ) -> Vec<(SystemId, f64)>

Find all systems within a radius (in light-years) of a reference point.

Uses the active galaxy’s spatial index. Returns empty if the active galaxy has no systems.

Returns (SystemId, distance_in_ly) pairs sorted by distance ascending.

pub fn nearest_planets<'a>( &'a self, from: &GalacticAddress, n: usize, filter: &BiomeFilter, ) -> Vec<(PlanetKey, &'a Planet, f64)>

Find the N nearest planets to a reference point, with optional filtering.

Uses the active galaxy’s spatial index. Returns empty if the active galaxy has no systems.

Iterates systems by proximity, then checks their planets against the filter. Returns (PlanetKey, &Planet, system_distance_ly) tuples.

pub fn planets_within_radius<'a>( &'a self, from: &GalacticAddress, radius_ly: f64, filter: &BiomeFilter, ) -> Vec<(PlanetKey, &'a Planet, f64)>

Find all planets within a radius that match a filter.

impl GalaxyModel

pub fn shortest_path( &self, from: SystemId, to: SystemId, ) -> Result<Route, RouteError>

Find the shortest path between two systems using A* (Dijkstra with zero heuristic).

If no graph path exists, falls back to a direct Euclidean hop.

pub fn tsp_nearest_neighbor( &self, start: SystemId, targets: &[SystemId], return_to_start: bool, ) -> Result<Route, RouteError>

Plan a route visiting all targets using nearest-neighbor greedy.

Uses Euclidean distances directly (not graph edges) for the TSP ordering.

pub fn build_route_from_order(&self, order: &[SystemId]) -> Route

Convert an ordered list of SystemIds into a Route.

pub fn two_opt_improve(&self, order: Vec<SystemId>) -> Route

Improve a route using 2-opt local search.

Iteratively reverses segments when doing so reduces total distance. Runs until no improvement is found (local optimum).

pub fn tsp_two_opt( &self, start: SystemId, targets: &[SystemId], return_to_start: bool, ) -> Result<Route, RouteError>

Plan a route using nearest-neighbor + 2-opt.

pub fn constrain_hops(&self, route: &Route, max_ly: f64) -> Route

Constrain a route so no hop exceeds max_ly.

Inserts intermediate known systems as waypoints when a hop is too long. Waypoints are marked with is_waypoint: true.

pub fn warp_jump_count(route: &Route, warp_range: f64) -> usize

Count the number of warp jumps needed for a route at a given range.

pub fn reachable_systems( &self, start: SystemId, warp_range: f64, ) -> Result<Vec<SystemId>, RouteError>

Find all systems reachable from start within a given warp range.

Uses DFS over the spatial index (no graph clone needed).

Trait Implementations

impl Debug for GalaxyModel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GalaxyModel

fn default() -> Self

Returns the “default value” for a type.