# Getting Started with the Gods Eye View Project: A Complete Developer Setup Guide

> Set up the Gods Eye View project easily. Clone the repo, configure env variables, and launch the Vite server for your spy satellite simulator. Get started today!

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

---

**To get started with the gods eye view project, clone the repository, configure environment variables for Google Maps and optional OpenAI access, and launch the Vite development server to run the browser-based spy-satellite simulator.**

The gods eye view project is an open-source, browser-based spy-satellite simulator built with **Vanilla JavaScript**, **CesiumJS**, and **Vite**. This visualization platform renders photorealistic 3D globes and overlays real-time data feeds for flights, maritime traffic, and satellites. This guide covers the essential setup steps, core architecture, and key source files you need to customize the application.

## Prerequisites and Environment Setup

Before running the simulator, you must obtain API keys for the mapping infrastructure and optional voice features. The application requires a **Google Maps API Key** to load photorealistic 3D tiles, while an **OpenAI API Key** enables the real-time voice command interface powered by 28 distinct tools.

Create a `.env` file in the project root:

```bash
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
VITE_OPENAI_API_KEY=your_openai_api_key

```

Install dependencies and start the development server:

```bash
npm install
npm run dev

```

## Understanding the Core Architecture

The gods eye view project cleanly separates concerns into three distinct systems: the rendering engine, the data layer manager, and the UI/voice interaction layer. According to the source code, these components communicate via custom events and normalized interfaces.

### The Rendering Engine in main.js

The entry point at [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) bootstraps the **Cesium Viewer** and configures the global rendering context. It initializes **Google Photorealistic 3D Tiles** via `Cesium.createGooglePhotorealistic3DTileset` and explicitly caps the render loop at 60 FPS to conserve battery on low-power devices (lines 69-135).

Initialize the viewer and load the Google 3D Tiles:

```javascript
// src/main.js – inside async init()
const googleApiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
Cesium.GoogleMaps.defaultApiKey = googleApiKey;

const tileset = await Cesium.createGooglePhotorealistic3DTileset({
  onlyUsingWithGoogleGeocoder: true,
});
viewer.scene.primitives.add(tileset);

```

The viewer configuration runs with minimal UI chrome and a custom credit container. If Google Tiles are unavailable, the system automatically falls back to the standard Cesium globe (lines 158-173).

### The Data Layer Manager

The `DataLayerManager` class in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) (lines 13-112) orchestrates all live data overlays including flights, ships, and satellites. It normalizes heterogeneous feed statistics into a unified state palette: **nominal**, **loading**, **degraded**, **stale**, **fallback**, or **unavailable**.

Register new data layers through the manager:

```javascript
// src/data/manager.js – after creating DataLayerManager instance
const dataLayerManager = new DataLayerManager(viewer);
dataLayerManager.register(flightsLayer);   // src/data/flights.js
dataLayerManager.register(trafficLayer);   // src/data/traffic.js

```

The manager implements **visibility intent** logic (lines 84-96) that guarantees ordered enable/disable actions and aborts superseded requests to prevent race conditions when users rapidly toggle layers.

### UI and Voice Integration

The interface layer spans [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js), [`src/styleManager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/styleManager.js), and [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevRealtime.js). These modules manage HUD panels, visual presets, post-processing effects, and hands-free control. The voice integration connects to the **OpenAI Realtime API**, offering AI-driven HUD summaries and map control without keyboard input (referenced in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) lines 21-22).

## Configuring the Map Stack Controller

Base map switching is handled by [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js), which manages transitions between Google 3D Tiles, Bing Maps, and OpenStreetMap. When the map source changes, the controller dispatches a custom `gev:map-stack-changed` event (handled in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) lines 77-89) so that data layers can adjust their rendering parameters or resolution settings.

Listen for stack changes to synchronize layer behavior:

```javascript
// Listen for map-stack changes (e.g., to adjust CCTV resolution)
window.addEventListener('gev:map-stack-changed', (e) => {
  const { stack } = e.detail;
  // React to stack change, e.g., update layer parameters
});

```

## Working with Data Layers

Each data module (e.g., [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js), [`src/data/traffic.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/traffic.js)) exposes a common interface implementing `getStats()`, `refresh()`, and `setEnabled()`. This standardization allows the `DataLayerManager` to poll, render, and display feed health uniformly using the `FEED_STATE_LABELS` palette (lines 13-20).

Toggle layers programmatically via the manager:

```javascript
// UI button click handler (simplified)
function onToggleLayer(layerId, enable) {
  const entry = dataLayerManager.layers.get(layerId);
  entry.module.setEnabled(enable); // each layer implements setEnabled()
}

```

## Enabling the First Run Experience

New users encounter a guided tutorial system via [`src/firstRunExperience.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/firstRunExperience.js), registered in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) at line 34. This mission-card interface introduces the data layers, map controls, and voice commands automatically on first launch, storing completion status in local storage to prevent re-triggering.

## Summary

- The gods eye view project requires **Vanilla JavaScript**, **CesiumJS**, and **Vite**, with API keys for Google Maps and optional OpenAI integration.
- [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) initializes the **Cesium Viewer** and Google 3D Tiles between lines 69-135, capping the frame rate at 60 FPS for power efficiency.
- [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) provides the **DataLayerManager** class to register, normalize, and control live data feeds with strict visibility intent handling (lines 84-96).
- [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) manages base map switching and emits `gev:map-stack-changed` events for cross-component synchronization.
- Voice commands via [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevRealtime.js) offer hands-free control through the OpenAI Realtime API and 28 specialized tools.

## Frequently Asked Questions

### What API keys are required to run the gods eye view project locally?

You must provide a **Google Maps API Key** to load the photorealistic 3D tiles. An **OpenAI API Key** is optional and only required if you want to use the real-time voice command features and AI-driven HUD summaries.

### How do I add a custom data feed to the simulator?

Create a new layer module that exports `getStats()`, `refresh()`, and `setEnabled()` methods, then register it with `dataLayerManager.register(yourLayer)` in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js). The manager normalizes your feed state through the `layerFeedState` system and handles lifecycle events automatically.

### Why is the application render loop capped at 60 FPS?

The render loop in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) intentionally throttles to 60 FPS to reduce power consumption on laptops and mobile devices. This optimization is implemented within the Cesium viewer configuration between lines 92-135 to ensure low-power usage without sacrificing visual smoothness.

### Can users switch base maps if Google 3D Tiles fail to load?

Yes. The [`src/mapStackController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/mapStackController.js) automatically falls back to standard Cesium globe rendering if Google Tiles are unavailable, and users can manually switch between Google 3D, Bing, and OSM base maps via the UI. The system notifies all layers of these changes through the `gev:map-stack-changed` event.