# adenta/fire_red_agent architecture

> Architecture diagram of the GitHub repository adenta/fire_red_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adenta/fire_red_agent
- Repository: https://github.com/adenta/fire_red_agent

## Overview

##### Project Type & Purpose
- This is a Ruby on Rails project designed to automate gameplay for Pokémon FireRed using a large language model (GPT-4) for decision making. It integrates with an emulator (RetroArch) for game control, reads game memory, processes game events, and manages a persistent “memory” of game states.
- Key functionalities include emulator integration (via OS-based scripting), game memory management, pathfinding, game text parsing through OCR, LLM integration for using GPT-4, and basic battle/conversation handling.

##### Analyzing the File Structure
- Top-level directories like “app,” “config,” “db,” and “lib” clearly indicate a Rails application.
- Inside “app/services,” you see multiple subdirectories: “game,” “intelligence,” “pathfinding,” “retroarch,” and “sky.” These represent distinct service components handling game memory parsing, decision-making (LLM), navigation (A* pathfinding), emulator interactions, and perhaps alternative approaches to reading emulator state.
- The “app/models” directory shows ActiveRecord models that store different types of game memories (e.g., GameMemory, MapEvents) and event types.
- Controllers and views are present. Although a UI isn’t the primary focus here, the web interface can be used for observation, logging, or control.
- Additional directories for configuration (e.g., config/initializers, config/routes.rb) and deployment (Dockerfile, Procfile.dev, .github/workflows) indicate a deployment pipeline and environment configurations.

##### Key Components
a. External Dependencies:
- Emulator (RetroArch): Runs Pokémon FireRed and sends game state data via memory and receives inputs.
- OpenAI’s GPT-4 API: Processes game context and decision-making into actionable game commands.
- External OCR service/tool: For reading screenshots to extract text, used in game text parsing.

b. Main Internal Components:
- Web Application (Rails):
- Controllers/Views: Interfaces for monitoring, debugging, or controlling the AI’s behavior.
- ActiveRecord Models: Store game memories and state information.
- Service Layers:
- Emulator Integration (app/services/retroarch and app/services/sky): Handles reading memory, sending inputs via OS scripting, and interacting with the emulator.
- Game State & Memory Management (app/services/game and models): Captures and persists game state changes, user actions, and events.
- LLM Integration (app/services/intelligence): Responsible for packaging game context and sending it to GPT-4, and interpreting responses.
- Navigation & Pathfinding (app/services/pathfinding): Implements algorithms (like A* as seen in “a_star_finder.rb”) to determine viable movement paths in the game map.
- Game Reasoning (app/reasonings): Provides structured input for the LLM and interprets game “reasonings.”
- Auxiliary Components:
- Background Jobs (app/jobs): For asynchronous tasks like periodic memory updates, polling for game state, or handling battle routines.
- Blueprints and Generators (app/blueprints, lib/generators): Likely used for scaffolding and defining structured interactions.

c. Data Flow & Relationships:
- The emulator continuously updates the game state, which is read by the “Game Memory Reading” services.
- Data is persisted in the database via ActiveRecord, forming a “diary” or long-term memory that provides context for the LLM.
- The “LLM Integration” service pulls relevant memories, along with current state, and communicates with GPT-4 to decide on actions.
- The decision then travels back down the pipeline to the “Emulator Integration” service, which translates the decision into keystrokes (via OS scripting) sent to the emulator.
- The “Pathfinding” component determines route planning by analyzing the map, facilitating movement commands.
- A clear feedback loop exists where the outcome of commands is recorded and then referenced in subsequent decisions.

##### Architectural Patterns & Design Principles
- Service-Oriented Architecture: Different concerns (game state, emulator I/O, AI decision making, pathfinding) are split into separate services.
- Separation of Concerns: Distinct modules handle external interaction (RetroArch), internal game logic (memory management, pathfinding), and artificial intelligence (LLM integration).
- Event-Driven/Feedback Loop: The system records outcomes (memory) from actions and uses this feedback to adjust subsequent behavior.
- Modular and Extensible Design: The use of generators, blueprints, and service objects suggests an architecture that can be extended or modified as needed.

##### Specific Elements
- A “Game Memory Reader/Parser” component that consumes raw game data and sends processed state information to the database.
- A “Persistence Layer” (Database) that shows ActiveRecord models for game memories, map events, etc.
- A “Pathfinding Module” connected to the “Game State” component, demonstrating route planning logic.
- A “LLM Integration” component representing API calls to OpenAI GPT-4, which receives structured state data (games memories, current map, possible actions) and returns decision commands.
- Game Memory Reader → Persistence (saving state)
- Persistence → LLM Integration (providing context)
- LLM Integration → Emulator Interface (command output)
- Pathfinding → LLM Integration (supplying navigation options)
- Components for “Battle Handler” and “Conversation Handler” to indicate how each specialized gameplay aspect is triggered and processed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    RE("RetroArch Emulator"):::external
    OCR("OCR Service"):::external
    GPT4("OpenAI GPT-4 API"):::external

    %% Game State & Memory Management Subgraph
    subgraph "Game State & Memory Management"
        GS("Game Services"):::persistence
        AR("ActiveRecord Models"):::persistence
    end

    %% Emulator Integration Subgraph
    subgraph "Emulator Integration"
        RA("RetroArch Integration"):::service
        SKY("Sky Integration"):::service
    end

    %% Web Application Subgraph
    subgraph "Web Application"
        CTRL("Controllers"):::ui
        VWS("Views"):::ui
    end

    %% Auxiliary Blueprints & Generators Subgraph
    subgraph "Auxiliary Blueprints & Generators"
        BL("Blueprints"):::auxiliary
        GEN("Generators"):::auxiliary
    end

    %% Other Service Components
    LLM("LLM Integration"):::service
    PF("Pathfinding Module"):::service
    GR("Game Reasoning"):::service
    BG("Background Jobs"):::background

    %% Data Flow Connections
    RE -->|"GameMemory"| GS
    OCR -->|"OCRData"| GS
    GS -->|"PersistData"| AR
    AR -->|"GameContext"| LLM
    PF -->|"NavOptions"| LLM
    GR -->|"ReasoningSchema"| LLM
    LLM -->|"APIQuery_Response"| GPT4
    LLM -->|"Keystrokes"| RA
    LLM -->|"Keystrokes"| SKY
    AR -->|"Logs_State"| CTRL
    BG -->|"PeriodicUpdates"| GS
    BG -->|"AsyncTasks"| LLM
    BL -.->|"Scaffolding"| GS
    GEN -.->|"Scaffolding"| GS

    %% Click Events
    click RA "https://github.com/adenta/fire_red_agent/tree/main/app/services/retroarch"
    click SKY "https://github.com/adenta/fire_red_agent/tree/main/app/services/sky"
    click LLM "https://github.com/adenta/fire_red_agent/tree/main/app/services/intelligence"
    click GS "https://github.com/adenta/fire_red_agent/tree/main/app/services/game"
    click AR "https://github.com/adenta/fire_red_agent/tree/main/app/models"
    click PF "https://github.com/adenta/fire_red_agent/tree/main/app/services/pathfinding"
    click GR "https://github.com/adenta/fire_red_agent/tree/main/app/reasonings"
    click CTRL "https://github.com/adenta/fire_red_agent/tree/main/app/controllers"
    click VWS "https://github.com/adenta/fire_red_agent/tree/main/app/views"
    click BG "https://github.com/adenta/fire_red_agent/tree/main/app/jobs"
    click BL "https://github.com/adenta/fire_red_agent/tree/main/app/blueprints"
    click GEN "https://github.com/adenta/fire_red_agent/tree/main/lib/generators"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef service fill:#90EE90,stroke:#000,stroke-width:2px
    classDef persistence fill:#FFB6C1,stroke:#000,stroke-width:2px
    classDef ui fill:#FFFFE0,stroke:#000,stroke-width:2px
    classDef background fill:#D3D3D3,stroke:#000,stroke-width:2px
    classDef auxiliary fill:#E0FFFF,stroke:#000,stroke-width:2px
```
