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

> Explore how Gods Eye View handles input using DOM events for map clicks, WebRTC for voice commands, and keyboard shortcuts for intuitive navigation. Learn more about this innovative input system.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-08-30

---

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

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

```javascript
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.

```javascript
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.

```javascript
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js), which validates targets via `isValidWorldFocusTarget` before animating the camera with `flyToWorldTarget`.
- **Voice commands** flow through [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.