Struct Navigator 

pub struct Navigator { /* private fields */ }

The veilwalking state machine: active world, in-flight travel, cooldown, arming.

Implementations

impl Navigator

pub fn new(worlds_root: impl Into<PathBuf>) -> Self

pub fn set_actor(&mut self, sub: Option<String>)

Name the traveler behind interactions: their Passport sub reaches behavior modules as actor.passport_sub. None → anonymous.

pub fn last_error(&self) -> Option<&str>

The most recent veilwalk failure (for a HUD notice), if any.

pub fn title(&self) -> Option<&str>

pub fn world_id(&self) -> &str

The active world’s stable id (its presence room key). Empty if none loaded.

pub fn locator(&self) -> Option<&str>

The active world’s Locator — the address bar. None before the first arrival or for a world loaded from a local file.

pub fn world_source(&self) -> Option<&str>

The active world’s raw manifest text — view-source, the Thread’s learn-by-copying primitive. None when no world is loaded.

pub fn world_description(&self) -> Option<&str>

The active world’s one-line description (may be empty) — for arrival cards.

pub fn home(&self) -> Option<&str>

The session’s home world Locator — by default, wherever the session opened.

pub fn set_home(&mut self, locator: impl Into<String>)

Override the home world (a browser preference).

pub fn back_history(&self) -> &[String]

The back-history Locators (most recent last). For a HUD/history panel.

pub fn can_go_back(&self) -> bool

Whether back() / forward() would go anywhere.

pub fn can_go_forward(&self) -> bool

pub fn back(&mut self, anchor: Vec3) -> bool

Veilwalk back to the previous world (the web’s back button). Returns whether a walk began — false when idle history is empty or travel is already in flight.

pub fn forward(&mut self, anchor: Vec3) -> bool

Veilwalk forward again after back() (the web’s forward button).

pub fn go_home(&mut self, anchor: Vec3) -> bool

Veilwalk to the session’s home world (a normal navigation — it forks history like any other walk). Returns whether a walk began.

pub fn sky(&self) -> Option<SkyNav>

The active world’s sky/atmosphere, if a world is loaded.

pub fn rules(&self) -> WorldRules

The opt-in game mechanics the active world enforces. Default all off (no world, home, or a place that declares no rules) — the browser stays a browser.

pub fn presence_relays(&self) -> &[String]

The active world’s presence relays (primary first, then fallbacks). Empty when no world is loaded or the world is solo.

pub fn presence_owner_required(&self) -> bool

Whether the active world’s room is owner-tied (presence.owner_required): when such a room closes, the browser SHOULD walk a guest back home.

pub fn is_traveling(&self) -> bool

Whether a veilwalk is in flight (destination being resolved/fetched).

pub fn colliders(&self) -> &[ColliderNav]

The active world’s solid volumes — placement geometry as oriented boxes for the browser’s physics. Empty when no world is loaded.

pub fn portal_preview(&self, to: &str) -> Option<&PortalPreview>

The live preview of a veil’s destination, once its fetch has landed — keyed by the portal’s to Locator. None while in flight, after a failed fetch, or for a veil that opted out (preview: "none").

pub fn portals(&self) -> &[PortalNav]

The veils in the active world — for a browser to render as doorways, draw on a minimap, or (headless) walk toward. Empty when no world is loaded.

pub fn armed(&self) -> bool

Whether the navigator is idle and armed — no travel in flight, off the arrival cooldown, and the player has stepped clear of every veil since the last traversal. When true, stepping into a veil will fire immediately; a browser can use this to show a “▶ step through” prompt only when it’ll work.

pub fn near_portal(&self, player_pos: Vec3) -> Option<(&str, &str)>

The veil the player is standing in front of, as (label, destination).

pub fn focused(&self, player_pos: Vec3) -> Option<Focus>

The inspectable placement the player is standing at (Codex pedestal or web signboard), as owned data for the HUD + inspect action.

pub fn interact(&mut self, player_pos: Vec3) -> Vec<Action>

The player interacted with whatever they’re standing at: dispatch the event to the placement’s bound behavior module and return the Actions it asks for — the browser performs them (the sandbox never touches IO). Empty when nothing is focused, nothing is bound, or the behaviors feature is off.

pub fn dispatch_event(&mut self, event: &Value) -> Vec<Action>

Deliver an async host event (e.g. a settled purchase_result) to every behavior module in the active world and return the Actions they ask for. Empty when no world is loaded or the behaviors feature is off.

pub fn tick_behaviors(&mut self, dt: f32) -> Vec<Action>

Advance the active world’s ticking behavior modules (declared "tick" in their on[]) — the world’s heartbeat. WASM modules tick every call; Weft modules tick at a steady ~4 Hz (fuel discipline) and their Actions are returned for the browser to perform — worlds that behave, not just react.

pub fn load_file( &mut self, loader: &mut dyn WorldLoader, path: &Path, anchor: Vec3, ) -> Option<Vec3>

Load a world from a local world.json (the startup path). Returns the spawn to teleport the player to.

pub fn reload_file( &mut self, loader: &mut dyn WorldLoader, path: &Path, locator: Option<String>, anchor: Vec3, ) -> Option<Vec3>

Re-apply a local world file in place — same world, fresh contents, keeping locator and touching no history. Build mode uses this after each edit to the home file: the scene rebuilds, but a reload is not a navigation, so back/forward don’t fork.

pub fn open(&mut self, locator: &str, anchor: Vec3)

Open a world by Locator (the startup entry to the live Thread). Kicks off the async resolve+fetch; the world loads on the next update poll. The first opened Locator becomes the session’s home unless overridden.

pub fn update( &mut self, dt: f32, loader: &mut dyn WorldLoader, player_pos: Vec3, ) -> Option<Vec3>

Per-frame: complete an in-flight veilwalk, or start one if the player stepped into a veil. Returns Some(spawn) to reposition the player.