The Command & Systems Codex
Exhaustive Triad Reference for All GOESnet Commands, Cockpit Systems, Controls & CLI Flags
Every entry in this codex answers three precise architectural questions: What it does (operational synopsis, flags, arguments, and visual effects), How it works (internal execution trace through C++20 routines, file descriptors, math formulas, and hardware registers), and Why it works (determinism guarantees, design safety boundaries, and engineering rationale).
đĄ GOESnet Terminal Commands & Celestial Queries (21 Commands)
Commands executed via Bulkhead Screen 0 and 1 using the retro 21-column pager console, interfacing with STARMAP.BIN and GUIDE.BIN.
| Command | Synopsis | Summary |
|---|---|---|
| CLR | CLR | Clears the terminal output buffer and resets screen paging |
| HELP | HELP [topic] | Displays built-in documentation and command syntax assistance |
| PAR | PAR <object>[:range] | Displays physical parameters and orbital properties of stars and planets |
| WHERE | WHERE <object> | Queries parent celestial body and system coordinates |
| ST | ST <object>[:range] | Sets ship navigation guidance lock on remote star or local planet |
| DL | DL <object>[:range] | Lists planetary system dependencies and notes count |
| CAT | CAT <object>[:range] | Opens the celestial guide and reads explorer annotations |
| CAST | CAST <object> <text> | Appends an immutable exploration note to a celestial guide entry |
| REP | REP <obj> <idx> <text> | Replaces an existing guide record owned by the player |
| DELE | DELE <object>[:range] | Deletes an exploration note and reclaims index entries |
| SL | SL [range] | Performs a stellar proximity search and lists nearby stars |
| PRI | PRI <object>[:range] | Exports formatted celestial guide records to the host filesystem |
| CLEAN | CLEAN | Defragments STARMAP.BIN and erases deletion tombstones |
| INBOX | INBOX [CHECK|CK|<file>] | Imports and validates external community starmap packets (.nsm/.json) |
| OUTBOX | OUTBOX [JSON|BIN|NSM] | Exports player discoveries to shareable packet archives |
| GALLERY | GALLERY | Indexes all captured photographic reconnaissance images |
| VIEW | VIEW [image_id] | Renders and exports a specific photo gallery image |
| LOG | LOG [EXPORT] | Displays travel logbook summary or exports Markdown/JSON journals |
| NAME | NAME <object> <label> | Assigns a permanent custom designation to a star or planet |
| BM | BM [LIST|ADD|GOTO|DEL|CLEAR] | Manages personal celestial bookmarks and surface waypoints |
| MOVIE | MOVIE [LIST|PLAY|EXPORT] | Controls Moviemaker decks, playback preview, and video rendering |
CLR : Clear Output Buffer
SYNOPSIS: CLR
Clears the entire text display buffer of Bulkhead Screen 1, resetting the scroll offset and returning the pager cursor to the top.
Dispatches GoesCommand::clear. The terminal state resets its 147-cell visible window memory to spaces and returns GoesResultAction::clear_output.
Prevents long search results from cluttering subsequent parameter readouts, maintaining clean cockpit visibility.
HELP : Command Documentation
SYNOPSIS: HELP [topic]
Displays an alphabetical index of all available GOESnet commands or detailed multi-line instructions for a specified topic.
Parses optional topic argument. Formats output lines into exact 21-character rows wrapped with decorative &&&&&&&&&&&&&&&&&&&&& dividers.
Self-documenting terminal ensures explorers can operate ship systems without referring to external manuals during flight.
PAR : Celestial Parameters
SYNOPSIS: PAR <object>[:range]
Retrieves astrophysical parameters for a named star or planet, including coordinates, mass, temperature, radius, and orbit index.
- Resolves
<object>againstSTARMAP.BINindex and active flight logs. - Derives star coordinates ($x, y, z$) within specified light-year search range (default 100).
- Calls
star_properties()orsystem_properties()to compute procedural astrophysics.
Ensures that celestial telemetry displayed on screen matches the procedural simulation physics exactly.
WHERE : Location & Parent Body
SYNOPSIS: WHERE <object>
Locates the parent star and planetary system holding a named moon or planetary body.
Inspects the target's StarmapRecord kind. If a planet, subtracts its orbital ordinal offset to resolve the host star ID, returning the primary star's name and galactic coordinates.
Prevents explorers from getting stranded when given an isolated planetary designation without stellar context.
ST : Set Navigation Target
SYNOPSIS: ST <object>[:range]
Locks the Stardrifter's autopilot and navigation HUD onto the specified celestial destination across interstellar or interplanetary space.
Resolves coordinates and injects guidance vector into EngineState. Sets GoesResultAction::set_remote_target for stars or GoesResultAction::set_local_target with planet index.
Direct bridge between terminal text commands and active 3D flight HUD steering.
DL : Planetary Dependencies
SYNOPSIS: DL <object>[:range]
Lists sub-bodies in a solar system and reports the count of recorded exploration notes attached to each planet.
Queries GUIDE.BIN records corresponding to the object's ID, tallying total annotations and printing a planetary summary.
Allows explorers to assess which worlds have been heavily surveyed versus virgin untouched planets.
CAT : Read Celestial Guide
SYNOPSIS: CAT <object>[:range]
Displays all recorded field notes, geological journals, and explorer logs attached to a celestial body.
Opens GUIDE.BIN in read-only mode, extracts 147-byte text blocks matching the celestial ID, and formats them for the screen pager.
Delivers the core narrative magic of Noctis: reading historical journals penned by travelers across two decades.
CAST : Record Field Note
SYNOPSIS: CAST <object> <text>
Appends your personal field observations and notes to a named planet or star in GUIDE.BIN.
Validates text length, constructs a new GuideRecord with timestamp and pilot ID, and appends the entry to GUIDE.BIN.
Every traveler leaves an indelible mark on the universe without overwriting procedural generation seeds.
REP : Replace Guide Record
SYNOPSIS: REP <object> <record_idx> <text>
Replaces the text of an existing exploration note previously authored by your ship.
Verifies ownership of the record at record_idx and rewrites the payload while rejecting any attempts to modify protected records.
Permits typo corrections and survey updates while enforcing authorship protection.
DELE : Delete Guide Record
SYNOPSIS: DELE <object>[:range]
Removes an exploration note from GUIDE.BIN.
Marks the record as inactive with a tombstone marker for compaction during subsequent CLEAN cycles.
Fast non-blocking deletion without risking disk corruption.
SL : Stellar Proximity Search
SYNOPSIS: SL [range]
Scans the local galactic sector and lists all nearby stars within the specified light-year radius (default 100 LY).
Iterates cubic sector coordinates surrounding the ship's current position, tests star existence via galaxy_star_at(), and formats names and distances.
Essential navigational radar when exploring uncharted sectors far from known trade lanes.
PRI : Export Guide Records
SYNOPSIS: PRI <object>[:range]
Exports all guide entries for the target object into a clean plaintext file in your exports directory.
Dumps guide strings to export/<object>.txt or initiates a browser file download on web builds.
Allows external reading, archiving, and analysis of vast planetary survey records.
CLEAN : Compact Starmap Database
SYNOPSIS: CLEAN
Defragments STARMAP.BIN, erases deletion tombstones, reclaims disk space, and rebuilds spatial search indexes.
Invokes compact_starmap() in [`src/goesnet_commands.cpp`](file:///home/gordonk/.gemini/antigravity/worktrees/public-builds/write_noctis_iv_docs/src/goesnet_commands.cpp), rewriting active records atomically and reporting reclaimed bytes.
Ensures that long campaigns with frequent renamings never degrade catalog read performance.
INBOX : Import Starmap Packet
SYNOPSIS: INBOX [CHECK|CK|<file>]
Inspects, validates, and merges external community starmap packets (.nsm or .json) into your local catalog.
- If
CHECKis passed, performs a non-destructive dry run reporting collision counts. - Verifies packet CRC32 and validates bounding limits.
- Applies conflict resolution: skips canonical bodies and merges non-conflicting labels atomically.
Enables asynchronous community cartography without central servers.
OUTBOX : Export Discoveries
SYNOPSIS: OUTBOX [JSON|BIN|NSM]
Exports all custom celestial names and field notes authored on your ship into shareable packet files.
Collects non-default records, computes CRC32 checksum, and writes data/outbox.nsm and data/outbox.json.
Simple one-command export for sharing starmap packets with other players.
GALLERY : Photo Gallery Index
SYNOPSIS: GALLERY
Lists all captured reconnaissance snapshots and panoramas stored on the ship with dates and image IDs.
Scans data/images/ for 8-digit BMP/PNG snapshots and formats a paginated index on Bulkhead Screen 1.
Quick in-cockpit catalog of photographic evidence collected across deep-space missions.
VIEW : Render Gallery Image
SYNOPSIS: VIEW [image_id]
Opens a high-resolution viewer for the specified reconnaissance photograph and exports it to your host machine.
Loads image buffer and triggers GoesResultAction::open_image, displaying the photo in the cockpit viewer or initiating browser download.
Seamless review of planetary photographs from within the terminal environment.
LOG : Flight Logbook
SYNOPSIS: LOG [EXPORT]
Displays an executive flight logbook summary or exports full travel chronicles to Markdown and JSON.
Queries active_flight_log(). When called with EXPORT, writes flight_log.md and flight_log.json to disk.
Automated journaling ensures every historic arrival and landing is permanently memorialized.
NAME : Celestial Designation
SYNOPSIS: NAME <object> <label>
Assigns a permanent custom designation to an unnamed star, planet, or moon in STARMAP.BIN.
- Sanitizes label text (uppercase alphanumeric
[A-Z0-9 _], max 20 chars). - Verifies target is not a protected canonical body (e.g. Fenia, Sol).
- Updates or appends a
StarmapRecordatomically.
Gives explorers naming rights over newly charted worlds while protecting established stellar landmarks.
BM : Bookmarks & Waypoints
SYNOPSIS: BM [LIST|ADD|GOTO|DEL|CLEAR]
Manages personal bookmarks for star systems, orbits, and planetary surface GPS locations.
Saves entries to bookmarks.ini. BM GOTO <id> automatically locks guidance computers onto the saved coordinates.
Eliminates the need to memorize 10-digit stellar coordinates when returning to favorite worlds.
MOVIE : Moviemaker Control
SYNOPSIS: MOVIE [LIST|PLAY <deck>|EXPORT <deck>]
Inspects recorded Moviemaker reels, launches in-cockpit CRT projection preview, or exports reels to video.
Scans movies/ directory. PLAY launches the projector player; EXPORT triggers background FFmpeg encoding.
Brings full cinematography controls directly into the command terminal.
đšī¸ Cockpit Flight Controls & Shipboard Navigation (8 Systems)
Central Onboard Manager
CONTROLS: Pages: [5] [R] [P] [X] | Rows: [6] [7] [8] [9]
Selects flight modes, navigation arrays, system preferences, or turns the glass display off.
Selected via eye tracking or hotkeys. Row keys 6â9 execute visible commands.
Streamlined ergonomic control over complex shipboard avionics.
Bulkhead Screen Focus
CONTROLS: Look & Click RMB on Wall Screens 0, 1, 2
Switches focus to GOES input (0), output buffer (1), or planetary landing atlas (2).
Adjusts cockpit camera orientation and transfers keyboard focus to terminal input buffers.
Physical spatial layout enhances immersion compared to flat 2D menus.
Flight HUD & Sliding Data Sheets
CONTROLS: Arrow Keys cycle targets | Data sheets update automatically
Displays remote stellar targets, local planetary orbits, and environment data sheets.
Renders vector reticles, apparent magnitude indicators, and velocity vectors directly onto window glass.
Crucial flight data remains in the pilot's line of sight during manual maneuvers.
Vimana Sub-Light Flight Mode
CONTROLS: Central Manager [5] -> Row [7] (Vimana)
Accelerates the Stardrifter across planetary distances toward selected orbital bodies.
Smoothly integrates sub-light acceleration curves, shifting cockpit star streaks and orbital distances.
Provides breathtaking visual transitions from deep space into planetary orbit.
Interstellar Hyperjump Drive
CONTROLS: Central Manager [5] -> Row [6] (Remote Target Jump)
Executes an instantaneous hyperjump across light-years to a locked stellar target.
Consumes one Lithium fuel charge, calculates target sector coordinates, and generates target star systems.
Instantaneous jumps make crossing an infinite procedural galaxy enjoyable and frictionless.
Cabin Illumination
CONTROLS: [+] Increase Brightness | [-] Decrease Brightness
Adjusts cockpit lighting from pitch black to bright cabin ambiance.
Scales ambient light shader uniforms applied to cockpit bulkhead textures.
Dimming cabin lights eliminates glass reflections when viewing faint stellar nebulae.
Cupola Airlock & Roof Hatch
CONTROLS: [Up Arrow] Exit to Roof | Proximity Doors to Re-enter | [S]/[T] Roof Speed
Exits the cabin to stand on top of the ship's exterior hull in space.
Transitions player state to roof geometry; toggling roof speed removes presentation pacing delays.
Delivers an awe-inspiring, unobstructed 360-degree panorama of the cosmos.
Cockpit Quick-Jump Hotkey
CONTROLS: Press [J] in Cockpit
Instantly centers the camera on Bulkhead Screen 1 with the bookmark command BM_ ready.
Bypasses manual camera rotation, pre-filling the console command buffer with BM .
Streamlines frequent waypoint management between orbital hops.
đĒ Planetary Surface Mobility & EVA Systems (7 Systems)
Locomotion & Speed Gears
CONTROLS: Mouse steering | Keys [0] through [9] (Speed gears) | LMB (Run/Swim)
Provides variable walking speeds across terrain, running, and swimming in planetary oceans.
Number keys set continuous forward velocity coefficients; LMB engages sprinting and buoyant swimming physics.
Enables effortless long-distance hiking across massive planetary landscapes.
Mouselook Mode Cycling
CONTROLS: Press [Down Arrow] to cycle modes
Cycles between Movement Mouse, Free Mouselook, and Inverted-Y Mouselook.
Updates camera pitch/yaw delta handlers in [`src/input.cpp`](file:///home/gordonk/.gemini/antigravity/worktrees/public-builds/write_noctis_iv_docs/src/input.cpp); preference persists in `current.niv`.
Accommodates diverse player preferences and modern flight simulator conventions.
Jump & Jetpack Dynamics
CONTROLS: [J] Jump | [Space] Jetpack Thrust | [C] Release/Cutoff
Allows leaping over obstacles and sustained jetpack flight across canyons and mountains.
Applies vertical impulse vectors; repeated taps provide ascending thrust countered by planetary gravity.
Crucial for exploring rugged alien topography and ascending steep crater walls.
Explorer's Visor HUD
CONTROLS: Automatic surface overlay | [Page Up]/[Page Down] Anti-radiation visor
Projects a 360° cardinal compass tape, digital heading, and GPS coordinates (lat, lon, elevation).
Calculates player spherical coordinates relative to planetary radius, rendering telemetry in real time.
Prevents loss of orientation on boundless procedural worlds.
Lander Return Beacon (LDR)
TELEMETRY: [LDR] 8-Way Arrow & Vector Range (e.g. [^] 142M or DOCKED)
Guides the explorer back to the landed capsule from kilometers away.
Computes spherical surface vector between current player position and capsule touchdown site.
Guarantees safe returns to the ship even during violent dust storms and nighttime expeditions.
Surface GPS Waypoint Drop
CONTROLS: Press [J] on Planetary Surface
Records a persistent GPS bookmark at your exact surface coordinates.
Appends planetary ID, latitude, longitude, and elevation into bookmarks.ini.
Allows marking rare geological formations, alien ruins, and scenic viewpoints for future visits.
Halogen Suit Torch
CONTROLS: [L] or [F] Toggle Torch
Projects an authentic forward spotlight beam from the helmet to illuminate dark planetary ground.
Applies perspective inverse-square distance attenuation, 4200K halogen blackbody tint, and `tanh` highlight compression.
Eliminates washed-out ground textures and flat horizon glow, preserving eerie nocturnal ambiance.
đˇ Photography & Reconnaissance Suite (5 Systems)
Standard Annotated Snapshot
CONTROLS: [M] or [*] (Space & Surface)
Captures an annotated photograph with location, star classification, and target telemetry burned onto the border.
Renders active frame buffer and burns text overlays before saving to data/images/NNNNNNNN.BMP.
Preserves full astronomical context for archival scientific logs.
Raw Snapshot
CONTROLS: [B] or [Delete] (Space & Surface)
Captures a pristine photograph with all telemetry, reticles, and border text suppressed.
Captures clean 3D scene buffers directly before UI composite passes.
Ideal for capturing wallpaper-worthy cosmic landscapes.
Panoramic 3-Frame Snapshot
CONTROLS: [N] or [/] (Surface Only)
Sweeps the camera across 3 consecutive frames, capturing a wide panoramic vista with telemetry.
Rotates view yaw in 3 calibrated arcs, rendering individual frames into temporary buffers before stitching.
Captures the colossal scale of planetary horizon curves and mountain chains.
Raw Panoramic Snapshot
CONTROLS: [V] or [.] (Surface Only)
Captures a seamless 3-frame panoramic panorama without HUD text or telemetry.
Combines 3 clean view passes into a unified panoramic wide-angle image file.
Produces stunning unobstructed landscape photographs.
Image Archive & Lossless PNG Export
CONTROLS: [F4] Open Archive | [D] Export Lossless PNG
Opens the in-engine photo gallery viewer and exports images directly to host desktop storage as PNGs.
Encodes 24-bit raw image data into standard PNG format, bypassing legacy TARGA/BMP limitations.
Immediate compatibility with modern image viewers and web browsers.
đŦ Moviemaker & Production Suite (5 Systems)
Moviemaker Panel (F3)
CONTROLS: [F3] Toggle Panel | [Enter] Start/Stop | [P] Pause/Resume
Opens the in-game movie recording studio interface in space and on planetary surfaces.
Initializes the movie_capture subsystem, displaying active deck, cadence, and frame counters.
Unified interface for frame-accurate game cinematography.
Deck Selection
CONTROLS: [Ctrl] + [+] / [-] Cycle Deck 001 through 999
Selects the target recording reel; occupied decks are protected against accidental overwriting.
Inspects movies/DDD/ directory paths, advancing to the next available empty deck.
Prevents loss of previously recorded footage.
Simulation Frame Cadence
CONTROLS: [+] / [-] Adjust Cadence (1 to 999 frames)
Sets how many simulation ticks elapse between each captured movie frame.
Ties recording directly to simulation updates rather than variable rendering refresh rates.
Guarantees smooth time-lapse or real-time videos free of frame drops.
In-Cockpit Bulkhead CRT Projector
CONTROLS: [V] or [Space] Play Deck | Left/Right Step | [L] Loop
Projects recorded movie decks directly onto the cabin display screen for review.
Streams sequential BMP frames with draggable timeline scrubbers and adjustable 6â60 FPS playback.
Allows in-universe screening of expedition recordings.
Modern Video Export (MP4 & WebM)
CONTROLS: [X] Export Selected Deck
Encodes image sequences to compressed MP4 or WebM video files with one click.
Launches asynchronous background FFmpeg workers on desktop or canvas blob download on Web.
Zero external video conversion tools required.
đī¸ Display & Shader Engine (6 Systems)
HUD Text Overlay
CONTROLS: [F2] -> [T] HUD Text Toggle
Toggles cockpit instrument text and reticles on or off.
Sets draw_hud boolean in display pipeline, suppressing HUD text rasterization passes.
Allows cinematic immersion when observing celestial horizons.
Visor Lens Flares
CONTROLS: [F2] -> [F] Cycle Lens Flare Modes
Cycles between Always On, Visor Only, and Always Off.
Modulates chromatic lens flare shader passes across bright solar disks.
Lets players choose between cinematic flare intensity or realistic dark sky viewing.
Border Display Mode
CONTROLS: [F2] -> [B] Seamless Border Toggle
Toggles between classic framed letterbox and modern borderless viewport filling.
Dynamically recomputes viewport aspect ratio scaling matrix in Raylib display backend.
Adapts cleanly to modern ultrawide and 16:9 displays.
Timewarp Multiplier
CONTROLS: [F2] Menu: [ [ ] Decrease | [ ] ] Increase (1x to 16x)
Accelerates planetary rotations and orbital movements.
Multiplies delta simulation time ticks applied to planetary orbit calculations.
Allows watching solar sunsets and moon transits unfold in seconds.
Resolution & Scale2X Modes
CONTROLS: [F2] -> [A]: [R] Internal Resolution | [U] Upscale Filters
Selects internal rendering resolution (320x200 up to 1280x800) and Scale2X/bilinear filters.
Allocates sized texture render targets and applies Scale2X pattern matching algorithms.
Maintains crisp pixel-art geometry on modern 4K monitors.
CRT & Sub-Pixel Shaders
CONTROLS: [F2] -> [A]: [C] CRT Shader | [G] Sub-Pixel Fidelity
Emulates retro CRT scanlines and enables sub-pixel celestial coordinate rendering.
Applies fragment shader scanline curves and sub-pixel float rounding in star rasterization.
Eliminates star shimmering while preserving genuine 1990s cathode-ray aesthetic.
đ Acoustics & Audio Mixer (4 Systems)
6-Channel Studio Mixer
CONTROLS: [F2] -> [Tab] Audio Menu | Arrow Keys adjust volume (0-100%)
Controls individual levels for Master, Music, Cabin, Propulsion, Weather, and Foley channels.
Adjusts miniaudio sub-bus gain multipliers; values persist in audio_settings.ini.
Custom audio balancing for personal preference and recording streams.
Generative Audio Modes
CONTROLS: [F2] -> [Tab] -> [G] Cycle Audio Modes
Cycles between GENERATIVE procedural synth, RECORDED music playlist, HYBRID, and OFF.
Enables or disables procedural 4-voice audio callbacks in [`src/audio.cpp`](file:///home/gordonk/.gemini/antigravity/worktrees/public-builds/write_noctis_iv_docs/src/audio.cpp).
Choose between dynamic real-time synthesis and classic soundtrack albums.
Instant Mute Toggle
CONTROLS: [F9] or [Ctrl] + [M]
Instantly mutes all sound output without changing slider positions.
Sets master output gain to 0.0 with soft anti-pop limiter ramping.
Convenient one-key silence when stepping away from the terminal.
Music Track Skip
CONTROLS: [N] Next Track | [P] Previous Track
Cycles through recorded ambient soundtrack tracks in data/music/.
Signals music_player stream to advance or rewind track file pointers.
Effortless control over recorded expedition music.
đģ Command-Line Interface (CLI) Utilities (6 Utilities)
--omega-drive & --standard-drive
SYNOPSIS: ./nivlr --omega-drive | ./nivlr --standard-drive
Equips infinite hyperjump fuel or restores conventional Lithium power (120 charges).
Modifies the fuel state integer in current.niv safely without corrupting save bytes.
Eliminates hex-editing save files to experience the legendary Omega Drive.
--reset-data
SYNOPSIS: ./nivlr --reset-data
Atomically wipes all save states and logs, restoring pristine seed catalog files.
Unlinks user save states and restores clean seed copies of STARMAP.BIN and GUIDE.BIN.
Safe, one-command fresh start without manually deleting user data folders.
--export-starmap
SYNOPSIS: ./nivlr --export-starmap [PATH]
Exports all player discoveries headlessly from the command line into an .nsm packet.
Runs export_starmap_packet() and terminates immediately with exit code 0.
Automated CI starmap backups and script integration.
--import-starmap
SYNOPSIS: ./nivlr --import-starmap <PATH>
Imports and merges an external starmap packet headlessly without launching the game.
Validates CRC32 checksums, applies collision resolution, and updates catalogs atomically.
Allows automated catalog synchronization across local network clusters.
--validate-starmap
SYNOPSIS: ./nivlr --validate-starmap <PATH>
Verifies the integrity of a starmap packet without applying modifications.
Parses binary structures and outputs detailed reports on valid, corrupted, or colliding records.
Guarantees safe inspection of untrusted community packets before installation.
--export-movie
SYNOPSIS: ./nivlr --export-movie <deck> [--export-fps 30] [--export-out path.mp4]
Encodes a recorded Moviemaker reel to MP4 video headlessly from the terminal.
Reads movies/DDD/ BMP files and streams them into FFmpeg libx264 encoders.
Batch video rendering pipelines for content creators and astronomers.