GlobeCraft is a Cargo workspace with one desktop application and four libraries.
flowchart TD
App[apps/globecraft] --> Core[globecraft-core]
App --> Data[globecraft-data]
App --> Render[globecraft-render]
App --> Assistant[globecraft-assistant]
Assistant --> Core
Render --> Core
Render --> Data
Data --> Core
Libraries never depend on the application. The workspace manifest owns versions,
package metadata and build profiles; Cargo.lock pins resolved dependencies.
apps/globecraft is the default member, so cargo run --release starts the app.
| Package | Responsibility | Entry points |
|---|---|---|
globecraft |
Native startup, input, UI state, font layout, styled shapes and texture upload | main.rs, app/mod.rs, app/ui, app/rendering.rs, app/overlays |
globecraft-core |
Command catalog and map-layer identities, double-precision math, camera/picking/flight, Unicode name normalization, language, Fluent catalogs and placemarks | camera, flight, math, language, localization, placemark |
globecraft-data |
Async HTTP, tiles, boundaries, local search, KML, settings, persistence and the network policy table | runtime, http, network, tiles, boundaries, search, kml, files, settings |
globecraft-render |
CPU rasterization, terrain relief, frame scheduling, geographic overlay preparation and tile priorities | worker, overlays, terrain |
globecraft-assistant |
The AI assistant as a sans-I/O agent: provider wire formats, tool calls over the command catalog, approvals, retries and compaction | agent, provider, tools |
The desktop uses eframe/egui/emath 0.36 with eframe's default wgpu UI backend
and upstream graphics backend fallbacks. The saved Uncap FPS preference selects
automatic non-vsync presentation at startup; other presentation defaults remain
unchanged. Background completion polling runs in App::logic, including
while hidden; panels and widgets run in App::ui using the root UI, which also
provides context access through dereferencing. The optional
compute renderer uses wgpu 30 independently of the UI backend, with shader tests
using its matching wgpu::naga re-export. The workspace requires Rust 1.95 and uses Edition 2024 with Cargo resolver 3.
Fixed-size geographic segments use array windows without changing arithmetic
order. Render benchmarks and device-loss fixtures inject private cache roots;
normal startup retains the existing platform cache path and limits. App-owned
frame timing gives repeated layout passes a zero movement delta, preventing held
navigation controls from advancing twice in a presented frame.
The app captures immutable camera/style/layer inputs. A render-owned coordinator holds one active job, one replaceable pending request and one completed frame. Provider, release, size and style changes reject incompatible results; compatible completed camera snapshots remain presentable during motion. Picking, borders, labels and scale use the displayed camera, keeping input and overlays aligned.
CPU rasterization uses the shared Rayon pool, eight-row tile batches and wide
four-lane f64 rays. Geographic conversion and LOD stay in f64; glam handles camera
matrices/quaternions and SIMD colors. Batch-local tile handles avoid repeated cache
reads and are released after the batch. Safe bytemuck casts describe byte pixels;
workspace code forbids unsafe Rust. Native macOS menus stay in the desktop
adapter; their callbacks queue actions and wake egui. Windows and Linux use
an in-window menu with the same command catalog, alongside sidebar controls.
The macOS menu registers Window/Help with the system, while About and shortcut
help use app-owned egui windows. Captions, enablement and checkmarks update from
the current language and app state. See desktop menus.
The sidebar can be collapsed from the persistent toolbar
button; its settings and sections remain available when reopened.
The toolbar ruler shortcut toggles the sidebar's existing ruler state and,
when enabling it, requests that its section expand and scroll into view,
retaining measurements and history. The camera shortcut uses the same screenshot job as the sidebar
and native menu. The file worker reserves screenshot names with create_new
and adds numeric suffixes on collisions before encoding the unchanged PNG pixels.
The pin shortcut shares the sidebar's At center placemark action, including
selected-folder insertion and localized default names. A pending reveal reopens
Placemarks and focuses/scrolls its existing name editor into view.
The top/bottom panel layout lives in app/ui/chrome.rs; the search input and
submission widgets live in app/ui/search_bar.rs. Query state, suggestion
merging/debouncing and search dispatch stay in app/search.rs, while
app/ui/suggestions.rs draws the results popup.
The toolbar status readout lives in app/ui/status.rs, with text at 90% of the
Body font size. It fits text using that same font, retains filename endings and
shows the full message on hover only when text or a file path is shortened.
The coordinator prepares CPU image data and matching overlay geometry before
publication. Egui uploads textures and builds styled shapes on its own thread.
RGBA buffers are reused when uniquely owned; screenshots retain immutable Arc
snapshots, so an export never reads a recycled frame. PNG encoding runs on the
bounded file worker.
App (apps/globecraft/src/app/mod.rs) holds what every feature reads and one state
per feature (roadmap 10.2). Shared, as fields of App itself: ctx, runtime, lang,
settings, cam, status and time. Everything else belongs to a feature state, a
plain struct in the feature's module:
| Field | State | Holds |
|---|---|---|
chrome |
chrome::ChromeState |
Header and ribbon: style scale, ribbon tools and peek, native menu (macOS) |
windows, panes |
windows::WindowsState, panes::PanesState |
Open windows and dialogs; what the Settings pages, Layers pane and colour keys show |
locale, saved, keys |
locale::LocaleState, saved::SavedSettings, keys::KeysState |
Language choice and system region; the settings on disk and their writer; service keys as typed |
motion, nav |
motion::MotionState, navigation::NavState |
A flight, the idle rotation, the followed ground; the navigator's drags |
tiles |
cache::TilesState |
The imagery cache, its Settings controls, tiles loaded ahead |
frame |
frame::FrameState |
Renderer, displayed frame and fade, render wake-up, screenshot in progress, diagnostics |
borders |
borders::BordersState |
Boundary data and loader, close-up place names, overlay geometry cache |
live |
live::LiveState |
Aircraft, vessels, satellites, aurora, airports, time zones, sea names, weather maps, traffic, and their drawn shapes |
map_data |
map_data::MapDataState |
Roads, transport and places of interest: tiles and shapes |
picked, pointer |
picked::PickedState, pointer::PointerState |
The picked flight and satellite; the pointer on the globe and the "What's here?" card |
files, updates |
files::FilesState, update_restart::UpdatesState |
File jobs and their status; the update service and restart |
search, places, measure, wayback, timeline, assistant, explorer, flat_earth, user_layers |
in the modules of the same name | The features split out first |
Rules for new state:
- A new field goes into the state of its feature; a new feature gets its own state
struct in its own module.
Appgains a field only for a new state or for a value that most features read. - A state's fields are
pub(super): the app's modules read them directly, asself.frame.texture. Borrows of different states (and of different fields of one state) stay disjoint that way, so a draw function can hold&mut self.live.geometryand&self.tiles.cachetogether; an accessor method onAppwould borrow all of it. - Logic that needs one state and a few plain inputs is a method of that state, taking
the inputs as a query struct (
LiveState::update_feeds(runtime, ctx, LiveQuery),MapDataState::update). Logic that reads several states stays animpl Appmethod in the feature's module. - States are declared in the order their parts were before the split, which is the order they are dropped in at exit.
globecraft_core::commands lists every action as a command: id, Fluent label/help keys,
icon, ribbon tab, JSON-Schema parameters and reach (view, files, destructive, interface).
App::run(id, params) (apps/globecraft/src/app/commands.rs) reads the command once with
commands::Command::parse: the id becomes a typed Command, grouped by feature
(Command::Camera(CameraCommand::FlyTo(FlyTo { lat, lon, .. }))), and the JSON
parameters become the command's own struct (commands/params.rs, read leniently: numbers
also as text, text trimmed). One handler per feature matches its group
(commands/camera.rs, places.rs, ruler.rs, files.rs, layers.rs, interface.rs,
settings.rs, info.rs; run_time, run_flight, run_satellite, run_user_data and
run_legend beside their states); a match must name every command of its group, so a
command without a handler does not compile. The table in commands/command.rs is the only
place that pairs an id with its variant; core tests check that it holds every catalogue
command once and that each parameter struct has exactly the parameters of its JSON Schema
(which stays hand-written: it is what the assistant reads). commands/state.rs reports enabled/checked state (App::command_state)
and commands/shortcuts.rs owns the keyboard shortcuts. The ribbon, File menu, macOS
native menu, shortcuts, context menu, controllers, Command Search and the assistant all
dispatch through App::run. globecraft_core::layers::MapLayer names every toggleable layer; data's Settings
stores their visibility (layers, plus the earlier sky and grid_numbers fields).
The window is laid out like RustGIS (Apache-2.0, see CREDITS.md): header,
ribbon, left/right panes, status bar and the globe in the central panel (app/ui/chrome.rs,
ribbon.rs, panes.rs, widgets.rs, theme.rs, icons.rs). The header also serves as the
title bar (app/ui/window_chrome.rs): macOS uses a full-size content view with hidden title
text and its native traffic lights; Windows and Linux keep the native title bar, buttons and
resize borders, so the header is an ordinary row there. The window title stays
GlobeCraft; the executable keeps its globecraft name. Theme tokens are applied to both
egui themes once per UI scale; egui switches themes itself. The render pipeline below is
unchanged by the interface. See interface.
globecraft-assistant builds provider requests and reads replies as plain data
(Anthropic, OpenAI Chat Completions and compatible servers, Gemini), and runs tool calls
through a Host trait. The desktop's app/assistant.rs sends requests with data's
model_http on the service runtime (streamed, bounded, waking egui per piece), applies
results on egui's thread and implements Host with App::run. Commands that touch files
wait for approval; interface-only commands are refused. See AI assistant.
Every raster source (imagery, maps, elevation, night lights) is described as data in
crates/globecraft-data/src/tiles/sources.json: a stable id (part of every tile key and of
the disk cache, never reused), a code, its kind, whether it is a basemap, how tiles are
addressed (an XYZ/WMTS-REST template, or Esri Wayback), the zoom range, tile size, cache
folder, attribution and prefetch policy. tiles::Provider is a source id with the built-in
sources as named constants; everything else asks Provider::source(). A new template source
is a new entry in the file. Each source's first failed download goes to the run log.
globecraft_data::network is the one readable table of built-in services: hosts,
request cadence, user agent and the Settings group each belongs to. Tile rows are
derived from sources.json, so adding a source adds its host automatically. The
desktop's Settings → Network page renders the table plus the dynamic hosts from
user-added layers and the assistant provider. HTTP clients take their user agents from
this module; the table is descriptive, not an interceptor. See
network policy for the current hosts, the provider-policy caveats
and the redirect/third-party limits.
globecraft-render::terrain marches each view ray through the Mapterhorn Terrarium
elevation (at most z15) until it meets the ground, so relief hides what lies behind it and
reaches the horizon. Elevation tiles decode into heights plus a pyramid of block maxima
(globecraft_data::tiles::Elevation); while a ray is above a block's maximum it jumps to
the block's edge, and only the last texels before the ground are walked one by one. The
elevation level follows the distance (about two pixels per texel), Mercator positions move
linearly between exact measurements, and a hit is refined by secant steps and shaded by the
local slope. Missing tiles are requested with screen priority and drawn at sea level until
they arrive.
The camera looks at the terrain height under the view centre (Cam::basis_over_ground,
eased in App::follow_ground), a tilted camera is kept 150 m above the ground beneath it,
and borders, names and live vector layers (roads, railways, ferries, airports, rivers,
parks and place/peak markers) are raised onto the relief from the loaded tiles
(overlays::GroundHeights). Terrain is drawn below 150 km and only on the CPU path (the GPU
renderer falls back).
The CPU renderer has no depth buffer, so overlays are also tested against that relief:
overlays::TerrainVisibility samples the straight eye-to-point line at 16 points and
reports the target hidden when the line passes below the ground. Borders split into their
visible runs, and roads, railways, ferries, airport markers, rivers, parks, place/peak
markers, vessels, placemarks, satellite subpoints and their labels are dropped where a
ridge or island hides them. Ships stay on the water surface but can still be hidden by
land. The test runs only when relief is drawn and the view is tilted at least 1°; the
exact top-down default view performs no elevation lookups. It reads the frame's loaded
elevation tiles and never requests new ones, and a missing tile reads as sea level. A
tilted view with relief therefore pays up to 16 elevation lookups per overlay point.
Live layers and the hidden illustration
Roads, AIS vessels, predicted satellite subpoints and traffic rasters use a
render-owned preparer and coalesced worker: one active request, one replaceable
pending request and one completed result. Inputs hold immutable Arc snapshots.
Moving raster frames carry geometry prepared for their camera; stationary data
refreshes use the same preparer off the UI thread. The app rejects geometry with
an incompatible camera, rectangle, DPI, scale, data identity or orbital time tick.
Roads/vessels/traffic reuse their prepared components when only satellite time
changes. Screen projection uses the selected Earth's surface; road hover tests
all visible fragments after a cheap prepared-bounds rejection.
Egui owns final styled mesh/label caches and texture upload. Traffic image projection and tile decode/stitching stay off egui; the data-owned feature and tile workers also perform OSM geometry conversion, AIS conversion and OMM conversion. Snapshots are allocated before publication, so applying a result swaps shared ownership instead of cloning fleets or road arrays. Service URLs, refresh intervals, retries, source fallback and draw order remain unchanged. Traffic completions from a replaced or cleared API key are discarded. Border tile loading status is separate from the bundled border/name datasets.
globecraft-core::orbit owns the existing approximate two-body propagation;
data owns CelesTrak format/epoch decoding. This preserves the existing educational
model, not SGP4 precision, and rejects invalid/non-finite orbital elements.
Normal live-layer labels use Fluent; errors retain structured causes until status
formatting. Roads' zoom limit uses the selected distance units (180 km / 112 mi).
The flat-Earth illustration remains a separate hidden scene with its existing
shortcuts, pan/rotate/zoom/reset/exit controls. It never changes EarthModel.
Its embedded image loads on the file worker. The app shares a static disk
layout (3,201 vertices / 6,144 triangles), caches tessellated stars/rim/surface
meshes per viewport/rotation/zoom/texture/DPI, and rebuilds only when that view
changes. Image completion after exit cannot reopen it. See the isolated
construction comparison in PERFORMANCE_BASELINE.md.
Render owns geographic visibility, border projection and ordered label candidates.
A packed geo-index R-tree indexes immutable boundary-line bounds, with conservative
3D horizon/frustum tests and dateline/pole handling. Dataset changes rebuild the
index; camera changes query it. Source order and visible line interiors are preserved.
The app caches one displayed set of egui shapes/galleys. Camera, viewport, DPI,
altitude, dataset, layers, language and text scale invalidate it. Tile arrivals and
unrelated UI updates reuse unchanged projections. Stationary changes use a coalesced
overlay worker; moving frames carry their matching geometry. Both workers also
tessellate the border segments into one white mesh per border kind, in an
app-provided step (render stays egui-free); the UI thread tints those vertices with
the current altitude and arrival fades. Font measurement, final label occupancy and
label shapes remain on egui. Label galleys live in the overlay cache across rebuilds
(egui keeps a galley only one frame), and a rebuild lays out at most 120 new names,
so a layer arriving with a thousand names fills in over a few frames instead of one
long one. Mutable rstar indexes
accepted screen rectangles in priority order, including touching-edge rejection,
padding and the 500-label limit. Placemarks and ruler edits remain immediate. Optional graticule label candidates
are prepared by the same background worker using the displayed raster grid step.
Render aligns candidates on shared column/row guides inside the visible globe,
swapping axes with view orientation. The desktop measures monospaced labels,
anchors them consistently and rejects collisions with place names and other grid
labels. Core owns disconnected ruler paths, bounded undo/redo history (100 edits),
path-aware distance totals, true-north heading formatting and initial great-circle
bearings; the desktop draws the status heading and compass. Pointer drags use core
move transactions so one drag is one history step. Native Edit menu commands
and keyboard shortcuts route to ruler history unless a text edit has focus. The
ruler coordinate editor accepts separate latitude/longitude decimal-degree fields,
uses core’s shared coordinates module to validate finite values within
±90°/±180°. Search coordinate queries use the same parser after splitting
comma, semicolon or whitespace separators. Core also validates decoded numeric
coordinates for geocoding, suggestions, GeoJSON boundaries/labels and KML I/O.
Data owns JSON/XML decoding and longitude-first format adaptation. Invalid
service coordinates are skipped; invalid KML coordinates return a typed error
before an import completes or an export touches its destination. The editor adds/edits points through
the same history. Input and editing preserve the stored f64 values without display
rounding. Realistic — WGS 84 (G2296) is the default; the 6,371.0088 km sphere remains
an optional model. The persisted selection routes camera, picking, rendering, geographic overlays and
geodesics through core's Earth-model boundary; model changes invalidate compatible
frame/overlay caches. See Earth models for supported calculations,
reference-frame limits and extension points. Precise entry alone does not establish
survey-grade accuracy.
The app owns one Tokio ServiceRuntime and injects handles/repaint callbacks.
Pooled reqwest clients enforce response limits, timeouts and retry policies.
Boundary JSON and PMTiles range reads also share a 120 s whole-request timeout,
so a body that trickles cannot outlive the connect/read limits, and all archive
range reads share six permits because they come from the same release host.
Network I/O runs asynchronously; bounded feature, tile-decoding and file workers
separate CPU-heavy parsing from interactive imagery. A panic in one of those
jobs is returned as that job's error, so the pool and the application keep
running. Six async tile workers use
48-job admission, current-view priority and delayed retries; stale queued detail
is retired while active work and coarse overview jobs remain.
Borders and place names come from OpenStreetMap vector tiles (OpenMapTiles schema,
served by OpenFreeMap) in boundaries::osm_tiles, streamed like imagery: a tile level
for the altitude (at most zoom 12), the tiles around the view, and ahead of a zoom
out the view's ancestors, a view-wide block at the next three levels up and the
world to zoom 3. A missing tile is drawn from its nearest loaded ancestor. Only land
borders (raw admin_level, disputed, claim and country-edge flags) and names are
kept, in a compact format, in memory (bounded by vertices, tiles to zoom 6 pinned)
and in a size-limited SQLite cache on disk (osm_borders.sqlite, least recently
used dropped first). Lines cut at tile edges are joined again, and the visible set
is composed off the UI thread and published as one replacing OsmBorders patch.
OpenStreetMap stores each border once, so no border is matched, cut or deduplicated
between sources. admin_level 2 draws as country, 3–4 as state, 5–8 as municipal
(from zoom 11); disputed and claimed lines draw dashed, every side's. Small names appear with the municipal lines, below municipal_detail_max_km.
The other map data sets (transport, roads, places, points of interest) stream through
vector_tiles::TileStream. Each keeps its vector tiles, gzip-compressed as downloaded,
in its own size-limited SQLite file on disk (map_data_<set>.sqlite, the same store
code and limit as the border cache, least recently used dropped first): a tile on disk
shows at once, one of an older build of the set shows and is downloaded again, and the
set's archive addresses are kept for offline starts.
The bundled Natural Earth 1:110m countries and places are the fallback: they draw
a cold or offline start before the first tile arrives, and the country polygons'
outer rings answer which country is under the camera (holes are drawn but excluded
from point-in-polygon lookup). Once tiles are loaded only tile lines are drawn.
Details: docs/BORDER_PIPELINE.md.
Loaded-name prefix search uses background-built Unicode-normalized FST indexes, with scanning during rebuilds. Ranking and remote-result merging remain explicit.
Boundary attribution (OpenStreetMap ODbL, OpenMapTiles, OpenFreeMap; Natural Earth public domain) is shown under the layer controls and on the globe while border tiles are in use.
GeoRust kml owns XML reading/writing. A bounded quick-xml preparation pass skips
empty Points, balances incomplete containers and wraps bare-coordinate fragments.
Core's placemark module owns a tree of Documents, Folders and point markers,
session-stable node IDs, inherited visibility and cycle-safe moves. Import/export
retains container order, names, descriptions, empty folders and visibility;
repeated saves do not introduce additional Document wrappers. The existing
first-coordinate policy for line/polygon Placemarks remains; this is not a
lossless editor for unsupported KML geometry, styles or network links.
The desktop draws disclosure arrows, full-width selectable rows and visibility
checkboxes, with a details editor for the selection. Compact rows use eight-point
indentation and vector folder/pin icons, independent of font glyph coverage.
The tree uses the height supplied by the sidebar layout; descriptions use a separate
three-line scrolling editor so long imported text cannot expand the sidebar.
Double-click flies to a
marker; drag onto a folder or My Places to move it. Creating a place/folder uses
the selected folder, otherwise the root. Hidden ancestors suppress map markers
without changing children's own visibility. File jobs capture the whole tree
at submission; decoding, encoding and filesystem work stay off the UI thread.
KML/KMZ I/O and screenshot encoding use an ordered bounded file service.
KMZ imports select the first KML entry in archive order without extracting
resources to disk. The entry is inflated with a 128 MiB limit on the bytes
actually decompressed (entry headers are untrusted), then takes the same XML
preparation pass and GeoRust KmlReader path as a plain KML file, so folder
visibility and malformed-document handling match. Archive and reader errors are
reported directly. Export writes the supported places tree as compressed
doc.kml. Embedded resources, styles and network links retain the existing
importer limitations.
Native dialogs
and result application belong to the app. Settings/language writes coalesce on a
filesystem worker and flush at shutdown; startup reads the small preference files.
Open KML source paths are stored separately in open-kml.json by that worker.
Startup reopens them in order on the file service, silently drops missing files
and rewrites the retained list; other failures remain visible and retry next launch.
Only paths are remembered, so unsaved tree edits require an explicit KML save.
A whole-tree save replaces the remembered sources with its destination to avoid
loading both the combined snapshot and its former inputs. Clear All empties the
tree and remembered list and discards pending KML results, without deleting sources.
Explorer image decoding (including the embedded Moon image) and planet document I/O use that same file service. Texture upload remains on egui's thread. Planet loads retain shared original encoded images, and saves snapshot their references, selected paths and name at submission. Re-saving an imported planet does not require its former image paths or re-encode its JPEG/PNG assets. Pending Explorer file controls are disabled, and selecting another body prevents a late load from changing the active body. The version-1 sidecar and version-2 embedded document formats remain supported.
Live aircraft use a data-owned asynchronous controller with one coalesced camera query and one latest immutable snapshot. It keeps at most one OpenSky and one ADSB.lol request active. JSON decoding and source merging/sorting use the bounded feature pool; the UI swaps shared snapshots, including shared immutable identifier strings. Coordinates use core validation and movement refresh uses core's mean-radius distance calculation. Provider URLs, response budgets, 17-minute/90-second refresh, three-minute failure retry and 30-second movement throttle remain unchanged. New requests pause when the layer or Earth body is hidden. Completed requests still publish and wake the UI. Cached global samples expire after 20 minutes; local samples retain the existing three-minute provider and 120-second position limits, with expiry publication coalesced to the one-second marker cadence. Re-enabling the layer with expired cached sources waits for background revalidation before displaying those positions again.
Render prepares aircraft projection and ordered label candidates in a bounded worker for stationary views, and alongside raster frames during motion. Both use the same preparer and the displayed camera. Geometry is reused for unchanged view/data/scale/DPI within a one-second time bucket; mismatched results never draw. One previous tick may remain visible while refreshing, up to two seconds old; expired geometry and older completions cannot replace a current result. Moving frames timestamp aircraft preparation at completion rather than raster submission. The 25-second extrapolation cap, icon geometry and label priority/spacing/count limits remain unchanged. Core owns the spherical destination calculation. The app owns Fluent statuses, English diagnostics, hover and font layout. It caches icon meshes and text galleys for the current geometry, preserving paint order; glyph UVs are not baked into cached meshes. No aircraft decoding, deduplication, sorting or geographic projection runs in a widget callback.
Data's updater service uses the async GitHub backend from self_update 1.3
on the injected service runtime. It retains the selected stable version, exact
tag and asset identity, requires GitHub's SHA-256 digest, coalesces progress through
one watch snapshot and wakes the UI after publication. Downloads/installations are
click-triggered and single-flight. Library verification/extraction/replacement
runs off the UI thread; macOS replaces and verifies the whole app bundle.
Debug builds and executables in Cargo output skip update checks independently
of their version. Managed installations use the official release-page fallback.
The desktop owns the centered bottom-bar notice and restart/save orchestration.
It reuses native save dialogs and the bounded file service, waits for file
completions without blocking egui, and closes normally. Startup relaunches only
after run_native returns, so preference flushing and app teardown precede restart.
A failed restart reopens the desktop with an inline error and the saved documents.
On macOS a normal quit flushes the settings writer and profiling log in on_exit
and then ends the process directly: AccessKit restores the content view's class
during window teardown while AppKit still observes it, so returning to eframe's
teardown crashes in _NSTouchBarFinderObservation. A pending update restart execs
the replacement from on_exit for the same reason; a failed restart reports to
stderr and exits instead of returning to the crashing teardown.
See releases for artifact names, install policy and integrity limits.
| Storage | Policy |
|---|---|
| Decoded tiles | Moka sync, weighted LRU, 256 MiB best-effort target; temporary overshoot and frame references are separate |
| Decoded vector tiles | Per set, LRU bounded by both tile count and a 64 MiB estimated decoded-heap budget; one tile is always kept, and the estimate excludes allocator overhead |
| Encoded imagery | MBTiles 1.3 through one tokio-rusqlite worker; 1 GiB managed-file target by default (Settings → Cache; 128 MiB before 2026-10-25), including SQLite overhead |
MBTiles separates providers, stable Wayback releases and encoded formats, converts XYZ rows to TMS, and lazily imports legacy tile files. Eviction favors coarse imagery and reclaims pages. Tiles publish before optional persistence. Clearing removes only owned imagery files, rejects old-epoch writeback, preserves decoded memory/settings/boundaries, and refreshes actual usage. SQLite R-tree/FTS5 support is available for auxiliary catalogs; it is not duplicated in the tile hot path.
Satellite overview warming covers zooms 0–4 globally: 341 tiles, 85.25 MiB decoded.
It runs while idle at 14,000 km or farther away, after visible work, with bounded
admission. Other providers stay on demand. The cache folder (paths::cache_dir) is
XDG_CACHE_HOME/globecraft when that is set, else Caches on macOS, LOCALAPPDATA on
Windows and ~/.cache/globecraft elsewhere; migrate_cache renames the
globecraft_tiles folder of earlier versions into place once. Preferences (settings.json, lang.txt, open-kml.json) and the
key files live in the configuration folder instead (paths::config_dir: Application
Support on macOS, APPDATA on Windows, XDG_CONFIG_HOME elsewhere), where cache
cleaners leave them; migrate_config moves them out of the cache folder once.
Settings exposes a System/explicit language preference separate from the resolved
session Lang. Core resolves supported system locales with English fallback;
the desktop uses its existing OS locale detector. Data persists system, en
or pt-BR in lang.txt, preserving old explicit choices. Missing preferences use
System Locale; selecting it never writes the resolved locale as an override.
Coordinates use degrees, internal altitude/distances use kilometers, and raster footprints
use meters. Core owns display conversions; the desktop detects the system locale
once and data persists the System/Metric/Imperial preference. GlobeCraft defaults to miles/feet for the US, UK, Liberia, Myanmar, Belize,
Bahamas, US Virgin Islands, Guam, Puerto Rico, Cayman Islands, Guernsey, Jersey
and Isle of Man. This application policy extends CLDR's US/GB length defaults
to include mixed/traditional mile usage; it does not claim uniform statutory
units in those regions. Other locales and unknown regions use kilometers/meters. Clicking the camera altitude opens an exact-value editor in its displayed unit.
Core validates/converts entries within the existing camera limits; the desktop
owns the editor and applies accepted values, cancelling active flight.
Camera altitude and scale bar share the selection; the ruler's Automatic option
also follows it. Its separate saved selector supports centimeters, meters,
kilometers, inches, feet, yards, miles, nautical miles, smoots, degrees and
arcseconds. Angular units represent accumulated central angle on the mean-radius
sphere. Football fields (100 yards, excluding end zones) are available everywhere.
The selector uses “Football fields” for US system locales and “American football
fields” elsewhere, with localized names. Optional selector-name overrides are
separate from short measurement labels; totals and segments retain “football fields”. KML/GeoJSON arrays are longitude-first; domain pairs are latitude-first.
UI strings live in embedded locales/{en,pt-BR}.ftl, with matching semantic keys
and named whole-message arguments. Errors/logs are English; normal UI messages
follow the selected language. See localization.
Opt-in profiling records pipeline and queue timings through a bounded background recorder. Normal builds compile it out. Component results and native measurements are documented separately; neither raster timing nor app-side texture submission is an application FPS guarantee. See contributing, CPU baseline.
The Earth overview raster can be computed by the globecraft-render backend
module with wgpu compute shaders (gpu/), then read back for the existing
egui view. GPU globe rendering is a beta, on by default wherever the gpu feature
is built in (Settings → Graphics turns it off); each adapter checks itself against
the CPU renderer before its first frame. The CPU path is always the fallback. Set
GLOBECRAFT_RENDERER=auto, gpu or cpu to override the default.
The Explorer, live meteorological/aircraft layers, moon and custom planet
remain integrated in apps/globecraft. See GPU_RENDERER.md
for hardware limits, performance and CPU-only build instructions.
Core owns body selection, spherical destination calculations and camera orbit/zoom
mapping. Render owns body meshes (positions/UVs/indices), weather compositing,
aircraft/ruler projection, scale-bar selection, raster sizing and frame keys.
These APIs use domain values, image buffers and emath, with no egui widgets,
texture handles or window objects. The desktop adapter uploads textures, measures
fonts, handles input and draws the returned geometry.
Data owns cloud/radar fetching, refresh/retry state, palette decoding, geographic
resource URLs and .globeplanet documents. Byte-oriented planet encode/decode APIs
support a frontend-provided legacy sidecar resolver; native path I/O is separate.
OS URL opening, speech commands and file dialogs remain desktop responsibilities.
This extraction prepares reusable logic; it does not make Tokio, SQLite, native
file services or GPU readback compile for WebAssembly. A web frontend still needs
browser transport/storage/execution adapters. Weather projection and body mesh
construction retain their current frontend scheduling; this PR does not add jobs.
app/ui/panes.rs draws the left pane (Layers, Places, Globe; Places can be pinned below the
others) and the right pane (AI Assistant, Measure). Data owns tolerant SidebarLayout
(left) and WorkspaceLayout (ribbon tab, collapse, right panes) persistence in the
existing settings file; name/description editing and tree mutations remain in
app/ui/places.rs and core.
Core owns CoordinateDisplay, CoordinateFormat and recognized coordinate
queries. The mgrs-convert adapter handles UTM/UPS/MGRS; presentation changes
never rewrite geographic values. Data persists tolerant format/precision fields
and the desktop owns labels/copy controls. Recognized invalid input fails locally
in English; ordinary addresses retain remote search. See
coordinate display.
Data owns tolerant appearance/navigation/cache preferences and applies configured imagery budgets at cache construction. The app owns searchable category widgets, OS font discovery and a bounded font-loading worker. Installed UI/map faces have independent bundled fallbacks; font application invalidates cached overlay text. Camera math remains in core. See settings.
Core owns normalized Explore bindings, response/deadzone policy, button edges and camera steps. Data persists bounded per-model profiles. The app's gilrs adapter polls hotplug/input, arbitrates focus and dispatches tool actions through menus; its settings module owns remapping and the live monitor. See controllers for device/platform limits.
Core's celestial frame adapter uses sofars to transform Earth-fixed rays into ICRF/J2000 directions. Data owns the pinned bundled image and bounded asynchronous decode. Render owns equatorial bilinear sampling, daylight visibility and shared CPU/GPU sky repair. App owns toggles, diagnostic/credit widgets and frame-matched screenshot attribution. See celestial background and the independent dataset manifest in assets/sky.