How amundsenzach/gravitic-zephyr works
Project type and purpose
• Type: Single-page, client-side web game (static site hosted on GitHub Pages).
• Purpose: Simulate realistic orbital mechanics in real time with interactive controls and dynamic trajectory guides.
File structure
• index.html – the application entry point.
• resources/styles/main.css – styling layer.
• resources/js/
– entities/ (CelestialBody, Spacecraft, OrbitPredictor) – core physics models and orbital prediction.
– game/ (GameState, Camera, RenderStarfield) – core game loop, world state management and rendering engine.
– ui/ (UIManager) – HUD overlays, buttons, trajectory guides.
– utils/ (InputManager, TouchControls, MathUtils) – input abstraction, math helpers and cross-device control support.
– main.js – orchestrates initialization, module wiring and the main animation loop.
README for additional architectural hints
• No backend or external services – all logic runs in the browser.
• Components focus on real-time physics, rendering, and user input.
Components
a. Browser Environment
– HTML renderer & CSS engine
– Canvas API / WebGL (if used)
– requestAnimationFrame loop
b. Application Shell (main.js)
– Bootstraps modules, starts the game loop
c. Input Layer (utils/InputManager, TouchControls)
– Captures keyboard, mouse, touch events
– Normalizes events into game commands
d. Core Game Engine
– GameState: holds positions, velocities of entities
– Camera: maps world coordinates to viewport
– RenderStarfield: draws background and entities
– OrbitPredictor (entities): computes guide arcs
e. Entity Models (entities/CelestialBody, Spacecraft)
– Data structures and physics update methods
f. UI Layer (ui/UIManager)
– Renders on-screen controls, HUD, trajectory guides
g. Utility Services (utils/MathUtils)
– Provides vector math, numeric integration helpers
h. Static Assets & Styles (resources/styles, index.html)
– CSS for layout, styling; HTML for script & style inclusion
Relationships and interactions
• index.html loads CSS and main.js
• main.js → initializes InputManager, GameState, UIManager, Camera, RenderStarfield
• InputManager → pushes input events into GameState or UIManager
• Each animation frame:
1. InputManager polls events → updates control state
2. GameState updates entities via physics (MathUtils, CelestialBody, Spacecraft)
3. OrbitPredictor computes paths for UIManager
4. Camera computes view transform
• All modules communicate directly in the browser memory space—no network calls.
Important architectural patterns
• Modular separation by concern:
– Physics (entities + utils)
– Rendering (game + ui)
– Input abstraction (utils)
• Central game loop coordinating state → update → render
• Singleton pattern for managers (only one InputManager, UIManager, GameState)