Crate bevy_a5 

bevy_a5

A Bevy plugin providing A5 geospatial pentagonal cell coordinates for planetary games.

bevy_a5 is to spherical / planetary games what big_space is to deep-space games — the same floating-origin idea, a different cell space, with A5-specific spatial queries on top.

What it provides

1. Cell-anchored coordinates. Position entities as (GeoCell, Transform) — which A5 cell, plus a small offset within that cell. The FloatingOrigin-tagged entity (your camera) defines the world’s reference cell; everyone else’s GlobalTransform is computed relative to it. When the origin’s local Transform exceeds its FloatingOrigin::recenter_threshold, the plugin hops to the neighbouring cell automatically.

2. Spatial queries on the sphere. grid_disk, neighbors, spherical_cap, parent/child/compact/uncompact — none of which big_space has, because A5 cells tile a sphere.

3. Display helpers. build_grid_line_mesh builds a ready-to-use Mesh for a slice of cells in one call; DrawCellOutline is a marker component that gizmos a cell’s pentagon every frame.

Cell-local frame convention

Within a cell, the local frame is vertex-aligned: the cell centre is (0, 0, 0), +Y is radial-up, and -Z (Bevy “forward”) points from the centre to the cell’s first boundary vertex. So a child entity at Transform::from_xyz(0.0, 0.0, -d) sits d metres along the cell’s “north” — the line from the centre to the first vertex. Adjacent cells have rotated frames; that’s the price of a cell-local convention.

Use orientation::cell_orientation / coord::tangent_frame if you need the geographic (north-up) frame instead.

Big-space rendering convention

The FloatingOrigin-tagged entity always renders at world (0, 0, 0) (rotation and scale preserved). Every other cell-anchored entity is placed in the origin’s local frame at its true sphere-space position relative to the origin. Move the origin by mutating its Transform.translation — never its GeoCell directly. The recenter system rebalances the (GeoCell, Transform) pair when the translation grows past the per-origin threshold, without moving the origin in world space. Recentres are visually invisible.

Quick start

use bevy::prelude::*;
use bevy_a5::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(BevyA5Plugins)             // plugin group: core + camera + hash
        .insert_resource(PlanetSettings::earth())
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    // Spawn the floating origin (camera) at Paris.
    let cell = GeoCell::from_lon_lat(2.3522, 48.8566, 9).unwrap();
    commands.spawn_floating_origin(cell)
            .insert((Camera3d::default(), FlyCam::default()));

    // Spawn an entity at a neighbouring cell's centre.
    let neighbour = GeoCell::from_lon_lat(2.3525, 48.8570, 9).unwrap();
    commands.spawn_cell_anchor(neighbour);
}

Roadmap

• Multi-planet support. PlanetSettings is a global resource today, so apps are restricted to one planet. A Planet component on a root entity with per-planet hierarchies is planned.

Modules

camera

Reusable fly-camera controller.

cell

The GeoCell component — an A5 pentagonal cell index for positioning entities on a planet.

commands_ext

Ergonomic command extensions for spawning A5-anchored entities.

coord

Coordinate conversion utilities between geographic (lon/lat) and 3D Cartesian coordinates.

debug

Debug rendering helpers for A5 cells.

geometry

Cell geometry extraction for rendering.

hash

Cell → entity spatial index.

orientation

Cell orientation computation.

origin

Floating origin marker component for camera / player entities.

planet

Planet configuration resource.

prelude

Convenient re-exports for common usage.

query

Spatial query utilities for A5 cells.

systems

ECS systems for transform propagation and floating origin management.

Structs

BevyA5Plugin

Core bevy_a5 plugin: floating-origin recentre, cell→world transform propagation, debug gizmos. No camera, no spatial hash. Use BevyA5Plugins for the full default set.

BevyA5Plugins

Default plugin group. Combines:

LonLat

Geographic coordinates using longitude and latitude in degrees.

Constants

WORLD_CELL