aether-zoning

Spatial load balancing, portals, and cross-zone authority

The aether-zoning crate handles spatial partitioning of large worlds across multiple server instances. It provides zone split/merge, cross-zone ghost entities, a portal system with aether:// URLs, authority transfer, and session handoff.

Overview

When a world grows beyond what a single server can simulate, the zoning system divides it into spatial zones, each owned by a different server. Key capabilities include:

• Zone split/merge that dynamically subdivides or consolidates zones based on entity density.
• Ghost entities that mirror objects near zone boundaries so physics and visibility remain seamless.
• Portal system for navigating between worlds or zones, supporting aether:// URL addressing.
• Authority transfer with a single-writer model that hands entity ownership between zones.
• Session handoff that migrates a player's session state to a new zone server.
• KD-tree partitioning for efficient spatial queries during split decisions.

Key Types

ZoningRuntime

The top-level runtime that evaluates zone load metrics and triggers split/merge decisions.

use aether_zoning::{ZoningRuntime, ZoningRuntimeConfig};

let config = ZoningRuntimeConfig {
    max_entities_per_zone: 5000,
    split_threshold: 0.8,
    merge_threshold: 0.2,
};
let runtime = ZoningRuntime::new(config);

SplitMergeManager

Monitors zone load and decides when to split overloaded zones or merge underutilized ones.

use aether_zoning::{SplitMergeManager, SplitMergeConfig, SplitMergeDecision};

let config = SplitMergeConfig {
    entity_threshold: 5000,
    cooldown_seconds: 60,
};
let mut manager = SplitMergeManager::new(config);
let decision: SplitMergeDecision = manager.evaluate(&load_metrics);

GhostManager

Maintains ghost copies of entities near zone boundaries for seamless cross-zone interactions.

use aether_zoning::{GhostManager, GhostPolicy, GhostEntity, Position};

let mut ghosts = GhostManager::new(GhostPolicy {
    boundary_width: 10.0,
    max_ghosts_per_zone: 200,
});

Portal

Defines a navigable gateway between zones or worlds, addressed by aether:// URLs.

use aether_zoning::{Portal, PortalShape, ActivationMode, AetherUrl};

let portal = Portal {
    destination: AetherUrl::parse("aether://hub.example.com/plaza")?,
    shape: PortalShape::Archway { width: 2.0, height: 3.0 },
    activation: ActivationMode::WalkThrough,
};

AuthorityTransferManager

Handles entity ownership transfers between zone servers using a single-writer protocol.

use aether_zoning::{
    AuthorityTransferManager, AuthorityTransition, TransferState,
};

let mut authority = AuthorityTransferManager::new();
authority.request_transfer(entity_id, source_zone, target_zone);

HandoffCoordinator

Orchestrates the multi-phase handoff when a player crosses a zone boundary.

use aether_zoning::{HandoffCoordinator, HandoffRequest, HandoffPhase};

let mut coordinator = HandoffCoordinator::new();
coordinator.initiate(HandoffRequest {
    player_id,
    source_zone,
    target_zone,
});

AetherUrl

Parses and represents aether:// URLs used for portal addressing.

use aether_zoning::{AetherUrl, AetherUrlError};

let url = AetherUrl::parse("aether://worlds.example.com/forest?spawn=north")?;
assert_eq!(url.host(), "worlds.example.com");
assert_eq!(url.path(), "/forest");

Usage Examples

Portal Navigation

use aether_zoning::{
    Portal, PortalState, PortalRenderer, PortalRenderState, PrefetchQueue,
};

// When a player approaches a portal, prefetch destination assets
let mut prefetch = PrefetchQueue::new();
prefetch.enqueue(portal.destination.clone(), PrefetchPriority::High);

// Render the portal preview
let render_state = PortalRenderer::render(&portal);

Session Handoff

use aether_zoning::{
    SessionHandoffEnvelope, PlayerStateSnapshot, SessionToken,
};

let envelope = SessionHandoffEnvelope {
    token: SessionToken::generate(),
    player_state: PlayerStateSnapshot::capture(player_id),
    timestamp: now,
};