How the Cockpit Mode Camera Works in God's Eye View: A Complete Technical Guide

God's Eye View implements the cockpit mode camera by binding the Cesium 3D camera to a selected aircraft through a three-layer architecture that handles target normalization, transactional entry with automatic rollback, and vision policy enforcement.

The cockpit mode camera in the open-source project bilawalsidhu/gods-eye-view locks the user's perspective to simulate a pilot's view from inside a selected aircraft. This system uses a transaction-based approach to manage camera ownership, handle entry failures gracefully, and maintain synchronization between the 3D viewport and the heads-up display (HUD).

The Three-Layer Cockpit Camera Architecture

The implementation splits responsibilities across three distinct logical layers to ensure robust tracking and clean separation of concerns.

Selection and Tracking Layer

This layer normalizes aircraft identification and enforces ownership rules. When a user selects an aircraft—via UI click, voice command, or API call—the system extracts a stable identifier combining layerId and id. The aircraftTrackingTarget function in src/cockpitTracking.js (lines 18-24) performs this normalization.

The restoreAircraftTrackingOwner(layer, id, …) function (lines 10-15) forces the target layer to claim tracking ownership, stopping any existing tracking on previous owners. This guarantees the cockpit's Cesium view remains attached to the aircraft even if the underlying layer changes later.

Entry Transaction Layer

The enterCockpitWithTracking function in src/cockpitTracking.js (lines 26-92) orchestrates the multi-step entry sequence with rollback capability:

• Attempt Tracking: If a selected layer/target is supplied, it attempts to track that target (lines 48-55)
• Activate Camera: Calls cockpitView.enter() to activate the cockpit camera (line 56)
• Failure Recovery: On failure, rolls back the attempted selection and restores the previous tracking target (lines 62-78)
• Exception Handling: If entry throws an exception, forces an exit without restoring tracking to prevent inconsistent states (lines 80-85)

Camera and UI Control Layer

This layer manages the actual camera switch and HUD updates. The controlCockpit method in src/voice/gevActions.js (around line 719) receives actions (enter, exit, next) and delegates to the cockpit-vision policy.

The cockpitVisionPolicy.js module contains pure functions that determine whether the cockpit view may be active given the current visual lane (e.g., preventing conflicts with "Contacts" or "World" modes). Once approved, UI components in src/ui.js—such as #cockpit-hud .cockpit-topline, #cockpit-speed-value, and #cockpit-altitude-value—populate with live telemetry from cockpitView.readAircraftInfo().

Step-by-Step Execution Flow

1. Target Normalisation: The system extracts layerId and id from the selected aircraft using aircraftTrackingTarget in cockpitTracking.js.

2. Force Ownership: restoreAircraftTrackingOwner stops existing tracking and assigns ownership to the target layer.

3. Enter Cockpit: enterCockpitWithTracking executes the entry transaction, attempting to track the target and activate the camera.

4. Camera Switching: controlCockpit in gevActions.js processes the action through the vision policy.

5. Vision Policy: cockpitVisionPolicy.js validates the camera change against current visual lanes, returning a boolean to allow or reject.

6. HUD Updates: ui.js refreshes cockpit HUD elements with real-time altitude, speed, and callsign data.

Implementation Code Examples

Programmatic entry requires calling enterCockpitWithTracking with the cockpit view instance and target aircraft metadata:

// Programmatic entry – track a specific aircraft and enter cockpit
import { enterCockpitWithTracking } from './cockpitTracking.js';
import styleManager from './styleManager.js';

const cockpitView = styleManager.getCockpitView(); // the Cesium cockpit view object
await enterCockpitWithTracking({
  cockpitView,
  selectedLayer: aircraftLayer,          // e.g. the “flights” layer
  selectedTarget: { layerId: 'flights', id: 'N12345' },
  currentLayer: aircraftLayer,
  rollbackLayer: aircraftLayer,
});

Voice commands route through the control_cockpit action:

// Voice command – the “control_cockpit” action is routed through gevActions
await runner('control_cockpit', { action: 'enter' });

UI button handlers implement the same flow with error handling:

// UI button – clicking “Enter Cockpit” triggers the same flow
document.getElementById('cockpit-entry').addEventListener('click', async () => {
  const result = await enterCockpitWithTracking({
    cockpitView: styleManager.getCockpitView(),
    selectedLayer: currentLayer,
    selectedTarget: currentTarget,
    currentLayer,
    rollbackLayer: currentLayer,
  });
  if (!result.entered) alert(`Failed: ${result.error}`);
});

Core Source Files

• src/cockpitTracking.js: Core entry transaction; normalises IDs, forces tracking ownership, and handles rollback logic
• src/cockpitVisionPolicy.js: Pure-function policy layer that decides whether the cockpit camera may be active
• src/cockpitMath.js: Resolves aircraft metadata via resolveTrackedAircraftInfo for tracking helpers
• src/ui.js: UI wiring for HUD components, cockpit entry buttons, and visual updates
• src/voice/gevActions.js: Exposes the control_cockpit action for voice and CLI entry points

Summary

• God's Eye View implements cockpit mode through a transaction-based camera binding system
• enterCockpitWithTracking in cockpitTracking.js provides atomic entry with automatic rollback on failure
• Tracking ownership is enforced by restoreAircraftTrackingOwner to prevent layer conflicts
• Vision policy in cockpitVisionPolicy.js prevents cockpit activation when conflicting visual lanes are active
• HUD synchronization occurs through ui.js after successful camera activation

Frequently Asked Questions

How does God's Eye View handle cockpit mode entry failures?

If enterCockpitWithTracking fails to activate the camera, it automatically rolls back the attempted selection and restores the previous tracking target (lines 62-78 in cockpitTracking.js). If the entry throws an exception, it forces an exit without restoring tracking to avoid inconsistent states (lines 80-85).

What prevents the cockpit camera from conflicting with other view modes?

The cockpitVisionPolicy.js module implements pure functions that evaluate the current visual lane context. These functions return a boolean that controlCockpit in gevActions.js uses to reject camera activation if conflicts exist with modes like "Contacts" or "World".

Which file manages the aircraft targeting logic for cockpit mode?

src/cockpitTracking.js contains the targeting logic. The aircraftTrackingTarget function (lines 18-24) normalizes aircraft identifiers, while restoreAircraftTrackingOwner (lines 10-15) manages ownership transfer between layers.

How is the cockpit HUD populated with live aircraft data?

Once cockpit mode activates, src/ui.js updates DOM elements including #cockpit-hud .cockpit-topline, #cockpit-speed-value, and #cockpit-altitude-value using telemetry retrieved from cockpitView.readAircraftInfo().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}