# neuralmmo/environment architecture

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

- Interactive diagram: https://gitdiagram.com/neuralmmo/environment
- Repository: https://github.com/neuralmmo/environment

## Overview

##### Main Components
- Core Engine (nmmo/core): This includes the basic environment setup such as configuration, map and terrain generation, game API, tiles, agent routines, and the overall realm/observation systems. It’s the heart of the simulation.
- Entity Management (nmmo/entity): This module manages game entities including players, NPCs, and the corresponding managers that handle creation, tracking, and behavior of each entity.
- Data Storage (nmmo/datastore): Handles persistence and efficient data operations (serialization, ID allocation, and use of numpy-based datastores) that support state storage and retrieval.
- Game Systems (nmmo/systems): Implements in-game mechanics (combat, inventory, item usage, exchange, droptable, skill handling) which enforce the simulation rules and interactions between entities.
- Minigames (nmmo/minigames): Provides specialized game modes like “center_race”, “king_hill”, etc. These modules act as sub-simulators or additional gameplay layers that extend the core environment.
- Rendering (nmmo/render): Responsible for visualizing the simulation. This includes overlays, replay mechanisms, client rendering, and additional utilities to generate the graphical or data visualization outputs.
- Task and Curriculum Management (nmmo/task): Houses systems for defining game tasks, predicates, and game state tracking. This serves as a framework for orchestrating scenarios, missions, or curriculum-level AI training.
- Utility Libraries (nmmo/lib): Contains helper functions and algorithms—such as A* pathfinding, seeding, spawning, team helpers, and event logging—that support the overall system functionality.
- Scripted Behaviors (scripted): Includes baseline scripted strategies (like attack and move routines) that might be used for testing or to serve as baseline agents.

##### Relationships and Interactions
- The Core Engine serves as the central hub where the simulation loop runs. It collects inputs from the entity managers and triggers updates across game systems.
- Entity Management interacts with both the Core Engine and Game Systems to update and process player and NPC behaviors.
- Data Storage is integrated by communicating with multiple components (core, entities, systems) to record and retrieve state information.
- Game Systems operate on data fed from the Core Engine and entity modules, handling detailed game mechanics.
- Task Management connects with the core systems and game systems to schedule and validate game scenarios or objectives.
- The Rendering module constantly reads game state information (from the Core or Data Storage) to generate visualization outputs.
- Utility Libraries support many of these modules by providing common functionality (e.g., pathfinding in core or systems, event logging across components).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each top-level module (core, entity, datastore, systems, etc.) performs a specific role, keeping the design modular.
- Layered Architecture: The design can be visualized in layers from the simulation’s core processing (engine and entities) up to external interactions (rendering and tasks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Core
    subgraph "Simulation Core"
        EM["Entity Management"]:::entity
        CE["Core Engine"]:::core
        GS["Game Systems"]:::systems
        DS["Data Storage"]:::storage
        TM["Task and Curriculum Management"]:::task
        UL["Utility Libraries"]:::utility
    end

    %% External Modules
    subgraph "External Modules"
        MG["Minigames"]:::minigames
        RD["Rendering"]:::render
        SB["Scripted Behaviors"]:::scripted
    end

    %% Interconnections within Simulation Core
    EM -->|"sends_inputs"| CE
    CE -->|"updates"| GS
    EM -->|"updates"| GS
    CE -->|"records_state"| DS
    GS -->|"schedules_tasks"| TM
    UL -->|"supports"| CE
    UL -->|"enhances"| GS

    %% Interconnections from Simulation Core to External Modules
    CE -->|"triggers_extensions"| MG
    CE -->|"visualizes_state"| RD
    DS -->|"provides_state"| RD
    CE -->|"baseline_actions"| SB

    %% Click Events
    click CE "https://github.com/neuralmmo/environment/tree/2.1/nmmo/core/"
    click EM "https://github.com/neuralmmo/environment/tree/2.1/nmmo/entity/"
    click DS "https://github.com/neuralmmo/environment/tree/2.1/nmmo/datastore/"
    click GS "https://github.com/neuralmmo/environment/tree/2.1/nmmo/systems/"
    click TM "https://github.com/neuralmmo/environment/tree/2.1/nmmo/task/"
    click UL "https://github.com/neuralmmo/environment/tree/2.1/nmmo/lib/"
    click MG "https://github.com/neuralmmo/environment/tree/2.1/nmmo/minigames/"
    click RD "https://github.com/neuralmmo/environment/tree/2.1/nmmo/render/"
    click SB "https://github.com/neuralmmo/environment/tree/2.1/scripted/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef entity fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef storage fill:#D7BDE2,stroke:#AF7AC5,stroke-width:2px;
    classDef systems fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px;
    classDef task fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef utility fill:#FDEBD0,stroke:#F0B27A,stroke-width:2px;
    classDef minigames fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef render fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef scripted fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
