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

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. 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:

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.
• 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, this object provides the caller with complete visibility into whether the operation succeeded and what went wrong if it failed.

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