Voyager Multi-Agent Orchestration

1. Project Overview

Voyager is a "Retro-Future" arcade space exploration game. Players pilot a craft, as Astronaut 311-C, to connect stars in Zodiac constellations within a shrinking time limit. If they connect all 12 constellations in time, they make friends with Zarg 966-Z, from Zargaborg. Players' completion times are scored in a leaderboard.

Three agents will collaborate to build this game. Agent A will build the game engine. Agent B will build the leaderboard. Agent C will validate their code by testing gameplay.

2. Technical Architecture and Ownership

Voyager is built on the following tech stack:

• HTML5 Canvas: High-performance 2D rendering.

• Vanilla JavaScript: Core game loop, physics, and state management.

• CSS3: Retro UI overlays and typography.

• Firebase: Easy hosting, authentication, and data persistence.

To prevent file collisions, the project is split into three primary functional domains:

• Agent A (Core Engine): Creates and owns public/game.js. Responsible for the game loop, physics, constellation data, and local state.

• Agent B (Social and Persistence): Creates and owns public/leaderboard.js. Responsible for Firebase initialization, Firestore queries, and high-score UI management.

• Agent C (Validation): Responsible for validating the functionality and interoperability of the code generated by Agents A and B. Uses gameplay to identify issues. Reads and writes any necessary file.

• Shared Resources (public/index.html and public/style.css): Agent A creates these files. All agents are authorized to read and write to these files.

3. The "Global Bridge" (Communication Contract)

Agents A and B must use a shared global object, window.Voyager, to coordinate state transitions without direct file dependency.

• State Enum: Use shared states: START, PLAYING, FAIL, WIN, LEADERBOARD.

• Hand-off Logic: When a game ends, game.js will call window.Voyager.showLeaderboard(score).

• Restart Logic: leaderboard.js will call window.Voyager.resetGame() to trigger a fresh start in the engine.

4. Visual and UX Standards

• Aesthetic: Phosphorescent, neon-heavy, and high-contrast.

• Palette:

• Background: #000033 (Deep Space Blue).

• Primary Accent: #00ffff (Neon Cyan).

• Secondary Accent: #ff00bb (Neon Pink).

• UI Components: Use existing overlay IDs: #start-screen, #fail-screen, #win-screen, and #leaderboard-screen.

• Typography: 'Press Start 2P' for arcade headings (make sure to import this font at the top of style.css!) and 'Courier New' for narrative text.

5. Data Schema (Firestore)

Agent B must adhere to the following Firestore structure to ensure compatibility with future analysis or curriculum metrics:

• Collection: scores.

• Document Fields:

• name: String (3 uppercase initials).

• score: Number (integer).

• timestamp: serverTimestamp.

• uid: String (from Firebase Anonymous Auth).

6. Firebase Initialization Strategy

• Reserved URLs: Do NOT hardcode a firebaseConfig object. Instead, use Firebase Hosting's reserved URLs in index.html for SDK loading and automatic initialization.

• SDK Loading: Include <script defer src="/__/firebase/12.8.0/firebase-app-compat.js"></script> and subsequent feature scripts (auth, firestore).

• Auto-Init: Include <script defer src="/__/firebase/init.js"></script> to handle the firebase.initializeApp() call automatically.

• JS Access: In your JavaScript files, access the initialized instance using const app = firebase.app();.

7. Development Constraints

• Asset Handling: No external image files; use procedural shapes (Canvas API) or embedded SVGs (for Zarg 966-Z) to maintain a lightweight, "vibe-code" feel.

• Inputs: Primary controls are Arrow Keys (movement), Shift (boost), Z (brake), and Enter (UI navigation).