Gods Eye View Input Handling: Map Clicks, Voice Commands, and Keyboard Shortcuts

Gods Eye View processes user input through three modular subsystems: custom DOM events for map click-to-focus interactions, WebRTC-based OpenAI Realtime API integration for voice commands, and global keyboard/pointer listeners for UI navigation.

The bilawalsidhu/gods-eye-view project implements a layered architecture that separates input validation, event dispatch, and execution across specialized modules. This design ensures that gods eye view input handling remains decoupled yet cohesive, allowing camera control, voice processing, and keyboard shortcuts to operate independently while sharing state through well-defined interfaces.

Map Click Input and World Focus Events

The project handles spatial interactions through a custom event system centered in src/worldFocus.js. When users click vessels, fires, or other world-owned targets, the UI dispatches a gev:world-request-focus event that undergoes validation before triggering camera animation.

Validating Targets and Registering Listeners

The requestWorldFocus function (lines 31-36) creates the event payload containing the target kind, id, position, and animation durationSec. Before processing, the system checks isValidWorldFocusTarget to ensure the clicked object qualifies for focus. The registerWorldFocusRequestListener function (lines 39-50) sets up the event consumer that routes valid requests through routeWorldFocusRequest.

// UI component handling a click on a map marker
function onMarkerClick(marker) {
  const detail = {
    kind: 'vessel',
    id: marker.id,
    position: marker.position, // Cesium.Cartesian3
    durationSec: 2.0,
  };
  // Sends a custom event that worldFocus.js will consume
  requestWorldFocus(detail); // ← src/worldFocus.js
}

Camera Animation Implementation

Once validated, the request invokes flyToWorldTarget (lines 60-82) to animate the Cesium camera. This function calculates the target’s position and applies pre-defined framing parameters including radius, range, and pitch to create smooth transitions.

import { registerWorldFocusRequestListener, flyToWorldTarget } from './worldFocus.js';

const dispose = registerWorldFocusRequestListener(window, (event) => {
  const target = event.detail;
  // `viewer` is the Cesium Viewer instance
  flyToWorldTarget(viewer, target);
});

// Later, call `dispose()` to remove the listener.

Voice Command Input Processing

Voice input handling resides in src/voice/gevRealtime.js and leverages the OpenAI Realtime API for natural language interaction. The system captures audio through WebRTC streams and converts speech into actionable function calls.

WebRTC Initialization and Audio Streaming

The initGevVoiceCommands function (lines 96-126) bootstraps the voice controller with dependencies including the Cesium viewer, styleManager, and sceneDirector. When users activate push-to-talk via the mic button or Space key, the controller creates a WebRTC peer connection, obtains a MediaStream, and opens a data channel to OpenAI’s endpoint. Local audio visualization runs through microphone and assistant visualizers while streaming continues in the background.

import { initGevVoiceCommands } from './voice/gevRealtime.js';

// Called once at app bootstrap
const voiceController = initGevVoiceCommands({
  viewer,
  styleManager,
  dataManager,
  sceneDirector,
  annotations,
});

// UI button click handler (wired in initGevVoiceCommands)
voiceController.buttonHandler(); // toggles start/stop automatically

Function Calling and UI Integration

As the Realtime API returns transcriptions, the system generates conversation.item.create events representing user messages. The controller queues response.create requests and processes incoming function-call events such as control_radio or set_layer_visibility by invoking corresponding tool runners. During active voice sessions, the UI disables competing actions like radio playback through the buttonHandler logic (lines 12-17) and restores them when the session ends, preventing input conflicts.

Keyboard Shortcuts and Global UI Input

The src/ui.js module serves as the central hub for traditional input methods, binding mouse, keyboard, and window events to application actions.

Global Shortcut Registration

Global shortcuts attach via standard DOM event listeners. Lines 3375-3378 register handlers for keydown and keyup events, while window-level listeners manage blur and visibility changes. These bindings support shortcuts like number keys 1-7 for visual styles, H for HUD toggles, and C for cockpit view.

// Inside src/ui.js constructor
document.addEventListener('keydown', this._globalKeydownHandler);
document.addEventListener('keyup', this._globalKeyupHandler);
window.addEventListener('blur', this._shortcutBlurHandler);
document.addEventListener('visibilitychange', this._shortcutVisibilityHandler);

Pointer and Visibility Management

Pointer and wheel events on the Cesium canvas drive map navigation, sharing gestures, and zoom operations. The visibility-change and blur handlers pause input processing when the tab loses focus, which prevents stray microphone activation and ensures keyboard shortcuts do not trigger while the user interacts with other applications.

Summary

• Map clicks dispatch custom gev:world-request-focus events through src/worldFocus.js, which validates targets via isValidWorldFocusTarget before animating the camera with flyToWorldTarget.
• Voice commands flow through src/voice/gevRealtime.js, establishing WebRTC connections to OpenAI’s Realtime API and executing tools like control_radio through function-call events.
• Keyboard input is captured globally in src/ui.js with blur and visibility handlers that pause processing to prevent conflicts with other applications or voice sessions.
• Each subsystem isolates concerns through module-specific validation, making the gods eye view input handling architecture testable and maintainable.

Frequently Asked Questions

How does Gods Eye View validate map click targets before moving the camera?

The project uses src/worldFocus.js to check clicks through isValidWorldFocusTarget, ensuring only vessels, fires, and world-owned entities trigger camera movement. Valid targets dispatch a gev:world-request-focus event consumed by registerWorldFocusRequestListener, which then routes the request through routeWorldFocusRequest before calling flyToWorldTarget to animate the Cesium viewer.

What technology powers the voice command system in Gods Eye View?

Voice input relies on the OpenAI Realtime API accessed through WebRTC peer connections established in src/voice/gevRealtime.js. The initGevVoiceCommands controller manages microphone MediaStream acquisition, audio visualization, and bidirectional streaming, converting speech into conversation.item.create events and executing function calls like set_layer_visibility through tool runners.

How does the UI prevent keyboard shortcuts from interfering with voice input?

The src/ui.js module binds visibilitychange and blur handlers (lines 3375-3378) that pause keyboard input processing when the browser tab loses focus. Additionally, the voice controller’s buttonHandler disables competing UI actions such as radio playback during active voice sessions, re-enabling them when the WebRTC connection closes.

Which module handles camera animation when focusing on map objects?

Camera animation logic resides in src/worldFocus.js. The flyToWorldTarget function (lines 60-82) receives validated focus requests and programmatically controls the Cesium viewer, applying specific framing parameters including radius, range, and pitch to smoothly transition the camera to the target’s Cartesian3 position.

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