X9000 System Architecture

NES-Style Game Console with AI-Powered Game Generation

High-Level Overview

flowchart TB
    subgraph Client["🎮 Client Layer"]
        UI["UI Components
(Panels, Controls)"]
        Engine["X9000Engine
(Main Controller)"]
        Canvas["Game Canvas
(256x256 NES Screen)"]
    end
    
    subgraph Core["⚙️ Core Systems"]
        GameLib["GameLibrary
(Local Storage)"]
        Sound["SoundEngine
(MML Audio)"]
        Debug["DebugUI
(Developer Tools)"]
        Sharing["SharingManager
(Cloud Sync)"]
    end
    
    subgraph External["🌐 External Services"]
        Pollinations["Pollinations AI"]
        Grok["Grok API"]
        OpenRouter["OpenRouter API"]
        BerrryAPI["berrry.app API"]
    end
    
    UI --> Engine
    Engine --> Canvas
    Engine --> GameLib
    Engine --> Sound
    Engine --> Debug
    Engine --> Sharing
    Sharing --> BerrryAPI
    Engine -.->|"Generate Games"| Pollinations
    Engine -.->|"Generate Games"| Grok
    Engine -.->|"Generate Games"| OpenRouter

Core Components

Core X9000Engine

Main controller orchestrating all systems
Manages game loop at 60fps
Handles rendering pipeline (tiles → sprites → text)
Processes user input (keyboard, touch, gamepad)
Coordinates AI game generation
Manages fullscreen mode and scaling

Data GameLibrary

Local game storage using localStorage
Stores up to 50 games with version history
Supports undo/redo (20 versions)
Automatic data migration from old formats
Storage cleanup on quota exceeded
Tracks shared game status

Core SoundEngine

NES-style audio synthesis
MML (Music Macro Language) parser
4 channel types: sq12, sq50, tri, noi
Web Audio API based
Supports sound effects and songs

API SharingManager

Cloud game sharing via berrry.app
User authentication handling
Public game discovery
Global leaderboards per shared game
Score submission system

UI Panel System

Reusable panel component
Toggle visibility with buttons
Open/close callbacks
Used by: Generator, Library, Settings, Debug, Help

UI DebugUI

Developer inspection tools
Tileset viewer with palette display
Layer inspector (tiles, sprites, text)
Sound log with MML display
Source code viewer

Data Flow Architecture

flowchart LR
    subgraph Storage["💾 Storage Layer"]
        LS["localStorage"]
        Cloud["berrry.app API"]
    end
    
    subgraph Data["📦 Data Structures"]
        GameIDs["Game IDs List
x9000-game-ids"]
        Games["Individual Games
x9000-game-{id}"]
        SharedIDs["Shared Game IDs
x9000-shared-game-ids"]
        Settings["User Settings"]
    end
    
    subgraph CloudData["☁️ Cloud Data"]
        SharedGames["Public Games
/api/data/game-{id}"]
        Scores["Leaderboards
/api/data/score-{userId}-{gameId}"]
    end
    
    LS --> GameIDs
    LS --> Games
    LS --> SharedIDs
    LS --> Settings
    Cloud --> SharedGames
    Cloud --> Scores
    Games -.->|"Share"| SharedGames
    SharedGames -.->|"Play"| Scores

Local Storage Schema

x9000-game-ids → Array of game IDs (ordered, newest first)
x9000-game-{id} → Individual game object with code, prompt, versions
x9000-shared-game-ids → Array of IDs for games user has shared
x9000-highscore → Local high score
x9000-settings → Prompt template, max tokens, etc.

Game Generation Flow

sequenceDiagram
    participant User
    participant Engine as X9000Engine
    participant API as AI API
    participant Parser as Code Parser
    participant Runtime as Game Runtime
    
    User->>Engine: Enter prompt + click Generate
    Engine->>Engine: Build prompt with template
    Engine->>API: Stream request (SSE)
    
    loop Streaming Response
        API-->>Engine: Code chunks
        Engine-->>User: Show progress
    end
    
    Engine->>Parser: Parse generated code
    Parser->>Parser: new Function(code)
    Parser-->>Engine: GAME object
    
    Engine->>Runtime: loadGame(GAME, code)
    Runtime->>Runtime: Build tileset atlas
    Runtime->>Runtime: Initialize game state
    Runtime-->>User: Game starts playing
    
    Engine->>Engine: Save to GameLibrary

Game Object Structure

meta → Title, palette (16 colors), tileset, soundbank
init() → Returns initial game state object
update(S, input, T, sfx) → Game logic, returns {nextState, G, S}
G → Graphics state: tileLayers, sprites, textLayer, gameOver, started, score

Rendering Pipeline

flowchart TB
    subgraph Input["🎮 Input Processing"]
        KB["Keyboard"]
        Touch["Touch Controls"]
        GP["Gamepad"]
    end
    
    subgraph Update["🔄 Game Loop (60fps)"]
        GetInput["Read Input State"]
        RunUpdate["Run game.update()"]
        GetGraphics["Get Graphics State (G)"]
    end
    
    subgraph Render["🖼️ Render Layers"]
        Clear["Clear Canvas
(Background Color)"]
        Tiles["Render Tile Layers
(Scrolling Backgrounds)"]
        Sprites["Render Sprites
(Dynamic Objects)"]
        Text["Render Text Layer
(ASCII Overlay)"]
        UI["Render UI
(Game Over, Score)"]
    end
    
    KB --> GetInput
    Touch --> GetInput
    GP --> GetInput
    GetInput --> RunUpdate
    RunUpdate --> GetGraphics
    GetGraphics --> Clear
    Clear --> Tiles
    Tiles --> Sprites
    Sprites --> Text
    Text --> UI

Layer System

Tile Layers → Array of scrolling backgrounds (8x8, 16x16, or 32x32 tiles)
Sprite Layer → Array of dynamic objects (any size up to 32x32)
Text Layer → 2D array of ASCII characters with bitmap font
Layers render in order: tiles → sprites → text → UI overlays

Module Dependencies

flowchart BT
    subgraph Modules["📁 JavaScript Modules"]
        SampleGame["sample-game.js
Game templates & factory"]
        EngineCore["engine.js
Constants & palette"]
        Sound["sound.js
Audio synthesis"]
        Debug["debug.js
Developer tools"]
        App["app.js
Main application"]
    end
    
    subgraph Exports["🔗 Window Exports"]
        WSample["X9000SampleGame"]
        WEngine["X9000Engine"]
        WSound["X9000Sound"]
        WDebug["X9000Debug"]
    end
    
    SampleGame --> WSample
    EngineCore --> WEngine
    Sound --> WSound
    Debug --> WDebug
    
    WSample --> App
    WEngine --> App
    WSound --> App
    WDebug --> App

Load Order

sample-game.js → Exports SAMPLE_GAME_CODE, FLAPPY_BIRD, JUMPER
engine.js → Exports SCREEN_SIZE (256), NES_PALETTE
sound.js → Exports SoundEngine class
debug.js → Exports DebugUI class
app.js → Main entry point, creates X9000Engine instance

API Integration

API Pollinations AI

Free, no API key required
OpenAI-compatible endpoint
Streaming support (SSE)
Multiple models available
Default choice for game generation

API berrry.app API

Backend for sharing
/api/auth/* → User authentication
/api/data/* → Private data storage
/api/public-data/* → Public game discovery
Visibility controls (public/private)

Sharing & Community

sequenceDiagram
    participant A as User A (Author)
    participant API as berrry.app API
    participant B as User B (Player)
    
    Note over A: Creates game locally
    A->>API: POST /api/data/game-{id}?visibility=public
    API-->>A: Share URL generated
    
    A->>B: Shares URL: ?play={userId}/{gameId}
    
    B->>API: GET /api/public-data/{userId}/game-{gameId}
    API-->>B: Game code + metadata
    B->>B: Plays game locally
    
    Note over B: Achieves high score
    B->>API: POST /api/data/score-{userId}-{gameId}
    API-->>B: Score saved
    
    B->>API: GET /api/public-data/users/score-{userId}-{gameId}
    API-->>B: Global leaderboard