# How the Cockpit Mode Rollback Mechanism Works in God's Eye View

> Discover how the cockpit mode rollback mechanism in God's Eye View ensures seamless transitions by capturing and restoring aircraft tracking states automatically upon failure or changes.

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

---

**The cockpit mode rollback mechanism in God's Eye View uses a transactional approach where `enterCockpitWithTracking` captures the original aircraft tracking state before attempting entry, then automatically restores it if the cockpit fails to initialize or the target aircraft changes.**

The cockpit mode rollback mechanism ensures users never lose their original tracking context when switching views in the God's Eye View open-source project. Implemented in the `enterCockpitWithTracking` function, this safety system guarantees that failed cockpit entries always return the user to their previous aircraft tracking state rather than leaving the UI in an ambiguous selection state.

## Transactional Entry Flow in `enterCockpitWithTracking`

The rollback mechanism operates as a multi-step transaction inside [`src/cockpitTracking.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitTracking.js). Each phase captures state necessary for potential recovery.

### Capturing the Current Tracking State

First, the function determines what aircraft is currently being tracked. It calls `cockpitView.readAircraftInfo()` and normalizes the result with `aircraftTrackingTarget` (lines 36-38). This creates the **restore target** snapshot used later if rollback triggers.

### Attempting Target Selection

If the user selects a new aircraft via `selectedLayer` and `selectedTarget` parameters, the code calls `selectedLayer.trackById` to begin tracking the new target (lines 48-55). This establishes the **active target** before cockpit entry.

### Executing Cockpit Entry

The function attempts to enter cockpit mode by calling `cockpitView.enter()` and wraps this in a try-catch block (lines 56-60). Success or failure here determines whether rollback activates.

## When Rollback Triggers

Rollback only occurs under specific failure conditions checked at line 62. The mechanism verifies two criteria:

- The cockpit entry failed (`!entered`)
- The attempted target differs from the original target (`key(activeTarget) !== key(restoreTarget)`)

If both conditions match, the system proceeds with restoration (lines 62-78).

## The Three-Step Rollback Process

When triggered, the rollback mechanism executes a precise cleanup sequence:

1. **Stop the new tracking attempt.** The code calls `activeLayer?.stopTracking?.({ origin: selectionOrigin })` to terminate tracking on the failed target (line 68).

2. **Restore the original aircraft.** The function invokes `restoreAircraftTrackingOwner(rollbackLayer, restoreTarget.id, ...)` to re-enable tracking on the previously active aircraft (lines 69-73).

3. **Handle restoration failures.** If the restoration itself fails, the system records an error while ensuring the UI doesn't enter an undefined state.

## Exception Handling for Critical Failures

If `cockpitView.enter()` throws an exception rather than returning a failure state, the mechanism follows a different path (lines 80-84). The code forces an immediate exit via `cockpitView.exit({ restoreTracking: false })`, leaving the tracker rollback as the authoritative state. This prevents partial cockpit initialization from corrupting the view state.

## Implementation Example

Here's how to use the rollback-aware entry function:

```javascript
import { enterCockpitWithTracking } from './cockpitTracking.js';

// Successful entry with current aircraft
const result = await enterCockpitWithTracking({
  cockpitView,
  selectedLayer: null,
  selectedTarget: null,
  currentLayer: aircraftLayer,
  rollbackLayer: aircraftLayer,
});
console.log(result.entered); // true

// Failed entry triggers automatic rollback
const failedResult = await enterCockpitWithTracking({
  cockpitView,
  selectedLayer: aircraftLayer,
  selectedTarget: { layerId: 'flights', id: 'invalid-id' },
  currentLayer: aircraftLayer,
  rollbackLayer: aircraftLayer,
});
console.log(failedResult.entered); // false
console.log(failedResult.error);   // Error message from rollback

```

The function returns an object containing `entered` (boolean) and `error` (string) properties (lines 88-91).

## Summary

- The **cockpit mode rollback mechanism** operates transactionally inside `enterCockpitWithTracking` in [`src/cockpitTracking.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitTracking.js).
- It captures the original aircraft tracking state before attempting any target switches.
- Rollback triggers only when cockpit entry fails and the target aircraft has changed.
- The restoration process stops new tracking and reactivates the original aircraft via `restoreAircraftTrackingOwner`.
- Exception handling forces immediate exit without tracking restoration, leaving the rollback layer in control.

## Frequently Asked Questions

### What triggers the cockpit mode rollback mechanism?

The mechanism triggers when `cockpitView.enter()` returns a failure state and the attempted target differs from the original tracking target. Specifically, the condition `!entered && key(activeTarget) !== key(restoreTarget)` at line 62 must evaluate to true. If the entry fails but the target hasn't changed, no rollback occurs because the original state remains intact.

### How does God's Eye View handle cockpit entry exceptions differently from entry failures?

When `cockpitView.enter()` throws an exception rather than returning false, the code catches the error and immediately calls `cockpitView.exit({ restoreTracking: false })` (lines 80-84). This bypasses the standard rollback restoration because the cockpit view itself may be in an unstable state. The function relies on the fact that the `rollbackLayer` already contains the correct tracking state from before the entry attempt.

### Can the rollback mechanism restore tracking if the original aircraft layer is unavailable?

The code attempts restoration via `restoreAircraftTrackingOwner(rollbackLayer, restoreTarget.id, ...)` (lines 69-73), but if this restoration fails, the error is recorded and returned in the result object. The mechanism assumes the `rollbackLayer` remains valid since it was captured at the start of the transaction. If the original layer becomes unavailable during the brief entry attempt, the system logs the failure but maintains UI consistency through the error state.

### What does the `enterCockpitWithTracking` function return?

The function returns a plain object with two properties: `entered` (a boolean indicating successful cockpit entry) and `error` (a string containing any error message encountered during entry or rollback). According to lines 88-91 in [`src/cockpitTracking.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/cockpitTracking.js), this object provides the caller with complete visibility into whether the operation succeeded and what went wrong if it failed.