GravitySandbox

GravitySandbox is a Qt Quick (C++/QML) prototype for experimenting with 2D gravitational simulations. Bodies are integrated with a symplectic Euler solver, trails illustrate recent motion, and a canvas-based scene provides interactive tooling for orbit setup.

Build & Run (macOS)

1. Install prerequisites

• Qt 6.8+ (with Qt Quick) – download the Qt Online Installer from qt.io/download and, during installation, select Qt 6.8 → macOS → Qt Quick.
  After installation, note the Qt directory (for example /Users/you/Qt/6.8.0/macos).
• CMake 3.16+ – install via Homebrew (brew install cmake) or download from cmake.org/download.

Verify both tools are available:

cmake --version
/Users/you/Qt/6.8.0/macos/bin/qmake --version

2. Configure and build

Qt provides a cmake wrapper in its bin directory, but calling the system CMake works as long as you tell it where Qt lives:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/Users/you/Qt/6.8.0/macos
cmake --build build

Replace /Users/you/Qt/6.8.0/macos with the path printed during the prerequisite check.

3. Launch the app

• From Terminal (shows console logs):

  ./build/GravitySandboxApp.app/Contents/MacOS/GravitySandboxApp

• From Finder (double-click friendly):
  1. Open the project folder in Finder.
  2. Navigate to build/GravitySandboxApp.app.
  3. Double-click GravitySandboxApp to launch the windowed application.

If you see a warning about the app being from an unidentified developer, right‑click the .app, choose Open, and confirm the prompt once—macOS will remember the choice afterward.

4. Optional: run automated tests

ctest --test-dir build

Controls

• Add Planet: Toggle the tool, click to set a position, and drag to indicate the launch velocity. Release to configure mass, radius, and color, then confirm to create the body. Drag distance is converted to m/s using the current zoom scale and simulation time scale.
• Pause / Play / Step: Pause freezes the simulation. Step advances exactly one fixed tick while paused.
• Time Scale Slider: Adjust the simulation speed multiplier.
• Gravity (G), Softening ε, Substeps: Edit numerical integrator parameters directly.
• Trails Toggle & Clear Trails: Disable trail recording or clear existing trails.
• Delete Selected / Reset: Remove the highlighted body or reset the entire scene.
• Quick Save / Load: Snapshot or restore the current scene. Saves are stored as JSON in the application data directory (platform dependent).

Camera & Interaction

• Pan: Drag with the mouse (when the Add Planet tool is inactive).
• Zoom: Use the mouse wheel to zoom around the cursor; the status overlay shows current scale and energy drift.
• Select / Inspect: Click a body to select it; hover reveals velocity vectors.

Files & Structure

• include/, src/ – C++ backend, simulation physics, and model classes.
• qml/Main.qml – Canvas renderer, HUD, and interaction logic.
• assets/ – Reserved for future art and audio.
• tests/ – QTest-based deterministic physics checks.

Persistence Format

Scenes are serialized as JSON with the following shape:

{
  "params": { "G": 10.0, "dt": 0.016, "substeps": 4, "...": "..." },
  "bodies": [
    {
      "mass": 50.0,
      "pos": [0.0, 100.0],
      "vel": [5.0, 0.0],
      "radius": 6.0,
      "colorRGBA": [204, 255, 102, 255],
      "alive": true
    }
  ]
}

Trail history is intentionally omitted to keep file sizes small; the simulation regenerates new trails after loading.

Diagnostics

Merge operations log their mass pairings and momentum deltas to the console. The HUD displays live FPS, energy drift, and pause status. Warning messages (e.g., clamp events) and informational updates (saves, loads) appear in the HUD footer.

Performance Notes

• The integrator clamps extreme accelerations and velocities, emitting warnings when they occur.
• Trail buffers are decimated and capped to avoid excessive allocations.
• Canvas rendering comfortably handles ~100 bodies at 60 FPS on a typical desktop GPU; reduce trail detail or time scale on slower machines.