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

> Discover how the cockpit mode camera in God's Eye View works. Learn about the three-layer architecture handling camera binding, target normalization, and vision policy enforcement in this technical guide.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: deep-dive
- Published: 2026-09-09

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) (around line 719) receives actions (`enter`, `exit`, `next`) and delegates to the cockpit-vision policy.

The [`cockpitVisionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevActions.js) processes the action through the vision policy.

5. **Vision Policy**: [`cockpitVisionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitVisionPolicy.js) validates the camera change against current visual lanes, returning a boolean to allow or reject.

6. **HUD Updates**: [`ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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:

```javascript
// 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:

```javascript
// 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:

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitTracking.js)**: Core entry transaction; normalises IDs, forces tracking ownership, and handles rollback logic
- **[`src/cockpitVisionPolicy.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitVisionPolicy.js)**: Pure-function policy layer that decides whether the cockpit camera may be active
- **[`src/cockpitMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitMath.js)**: Resolves aircraft metadata via `resolveTrackedAircraftInfo` for tracking helpers
- **[`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)**: UI wiring for HUD components, cockpit entry buttons, and visual updates
- **[`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitVisionPolicy.js) prevents cockpit activation when conflicting visual lanes are active
- **HUD synchronization** occurs through [`ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/cockpitVisionPolicy.js) module implements pure functions that evaluate the current visual lane context. These functions return a boolean that `controlCockpit` in [`gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) updates DOM elements including `#cockpit-hud .cockpit-topline`, `#cockpit-speed-value`, and `#cockpit-altitude-value` using telemetry retrieved from `cockpitView.readAircraftInfo()`.