03 / Spatial Archive Gumaru

Gumaru treats history as an authored graph of evidence rather than a linear narrative. The engine models a world using strict constraints—birth records, handwritten letters, land deeds, and maps—and asks the user to move through these fragments to assemble the truth.

The experience is spatial: stories gather weight because they happen in concrete places, over specific decades, leaving traces that are indexed, queried, and cross-referenced.

The Gumaru interface is split into two primary visual spaces: the Graph Canvas (utilizing Cytoscape.js for node editing) and the 3D Spatial Globe (using MapLibre GL).

• Parchment Globe Overlay: The 3D globe renders with a simulated physical parchment paper texture and horizon edge-blur mask to completely eliminate aliasing at the globe's visual boundaries.
• Vintage Ink & Sepia Styling: Map styling overrides administrative lines to look like sepia watercolor halos with high blur and low opacity, blending modern borders with a high-resolution Natural Earth background.
• Camera-Aware Sunlight & Shading: Sunlight direction shifts dynamically with the timeline playhead. During cinematic sweeps, day/night shadow gradients rotate based on map bearing and pitch, softening at low-angle viewing heights.
• High-Resolution Offline Tiles: Renders map details completely offline by packaging Natural Earth II high-resolution raster tiles served through local file endpoints.

The engine processes a schema containing nine distinct node types and their relationships:

• Person & Group: Individual entities and family/collective groupings.
• Place: Mapped coordinates with administrative paths (e.g. Malaysia / Penang / George Town).
• Event: Instantaneous or span-based occurrences (purchases, voyages, estate sales) with participant roles.
• Document: Physical evidence (written ledger entries, photos, letters) containing raw text or MIME attachments.
• Concept & Hypothesis: Abstract items (like signature marks) and theories linking events or authorship with variable confidence scores.
• Scene & Behavior: Cinematic playbacks and animated movement coordinates.
• Static 3D GLTF Models on Nodes: Any graph node (except Scene and Behavior nodes) can host a custom 3D model (GLTF/GLB) directly in the map coordinate space. The engine projects models onto MapLibre's globe custom layer using Babylon.js, allowing customization of size, rotation, altitude, and color.

Gumaru features a comprehensive system to author and play back time-scoped cinematic sequences directly on the 3D globe:

Scene Editor Workspace: When editing, the scene designer takes over the entire viewport—hiding the Cytoscape graph canvas and properties panel. From the map-hosted toolbar, creators can position camera cues (bearing, pitch, zoom, target coordinates), establish character movement paths, type narrative subtitle overlays, and sequence behaviors chronologically.

3D Primitives & Style Overrides: Authors can place Babylon.js-backed 3D meshes (box, sphere, cylinder, cone, plane) with rotation outlines onto the map. Edits made at specific times along the timeline generate keyframes that define time-scoped style overrides (scale, altitude, rotation, visibility) which interpolate smoothly during playback.

Automated Playback Pacing: The Scene Player applies auto-speed mechanics during playback, fast-forwarding through quiet chronological gaps between cues while using text-length heuristics to calculate precise, readable pauses for subtitle text overlays.

Gumaru pairs LLM-based text generation with local Text-to-Speech audio rendering to automatically build rich, voiced narratives:

Document Generation: When a user creates a new Document node, the engine injects its local graph relationships into an LLM template. The model compiles a contextual document matching the era—such as a handwritten Eurasian letter from 1920 or a secondhand shop ledger entry from 1968.

Documentary Audio Generation: Using a bundled, offline Kokoro text-to-speech runtime (powered by `tts.rocks` inside the Electron client), the engine generates voiced narration for nodes. During timeline playback, the camera focuses on each node and automatically plays its documentary audio file, pausing the playback playhead until the narration finishes before moving to the next chronological event.

While Gumaru Studio is designed as a desktop-native application (harnessing Electron for local filesystem operations and batch offline Kokoro TTS audio compilation), projects are compiled for public consumption as static web packages.

The export pipeline tree-shakes the Cytoscape graph editor, resizable side panels, and authoring code to output a clean, map-centric showcase. It copies and bundles Natural Earth map tiles, 3D GLTF files, and generated voice WAV files into a standalone directory.

The resulting site runs on any standard web host and is fully responsive—supporting fluid touch gesture mapping, timeline seeking, and audio player playback across both desktop browsers and mobile devices.