# fy-/fyworld architecture

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

- Interactive diagram: https://gitdiagram.com/fy-/fyworld
- Repository: https://github.com/fy-/fyworld

## Overview

##### Project Type and Purpose
- FyWorld is a Unity-based, top-down base-building / simulation game. It’s organized as a “mega-tutorial” open-source project: the Unity Editor + C# code drive simulation (entities, AI, world), while assets (textures, shaders, prefabs) supply visuals and UI.

##### High-Level Components
a. Unity Editor & Project Settings
- Manages build, input, graphics, scene loading (ProjectSettings/*, Packages/*).
b. Assets
- Resources: Textures, Shaders, Materials (for world/tiles/units).
- Prefabs: UI elements, FX, Character panels.
- Third-party libs: TextMesh Pro, Priority Queue.
c. Core Simulation
- World Layer: Map, GroundGrid, TilableGrid, LayerGrids (World/*).
- Entities: Ground, Plant, Mountain, Building, Inventory, Tick (Entities/*).
- Definitions: DefsLoader + Def classes (Definitions/*) load JSON/XML data into in-memory definitions (e.g. BuildingDef, TaskDef).
- Game Loop: GameManager orchestrates fixed ticks, updates world and entities.
d. Character & AI Systems
- BaseCharacter, CharacterStats, CharacterMovement (Characters/*).
- AI: BrainNode, PathFinder, Target, Tasks, per-node logic (Characters/AI/*).
e. Controllers & UI
- Input/UI controllers: MenuController, WindowController, DragController, TileSelectorController, CameraController (Controllers/*).
- UI windows and panels, tied to prefabs under Assets/Fy/Resources/Prefabs/UI.
f. Rendering & Visuals
g. Helpers & Tools
- Utility classes (PerlinNoise, GameObjectPool, Utils, WordUtils*).
- PythonUtils folder: external Python scripts for offline generation or analysis.

##### Interactions and Data Flow
- On start, DefsLoader components read data files → populate Definitions.
- GameManager invokes WorldUtils to generate Map & Grids → instantiate Entities with their Defs.
- Each tick:
- Entities.Tick triggers update: CharacterBrain selects Task (via AI.BrainNode, Tasks classes) → PathFinder calculates path → CharacterMovement moves character → Entities state updates (Inventory, Stats).
- Controllers listen for user input (mouse/keyboard) → modify game state (e.g., place buildings, change camera, open UI windows).
- Logging and editor settings managed by Unity ProjectSettings; assets hot-reloaded by Editor.

##### Architectural Patterns and Design Principles
- Data-Driven: Definitions loaded at runtime decouple data from code.
- Entity-Component-System flavor: Entities maintain data, various systems (AI, Movement, Rendering) operate on them each tick.
- MVC-like UI: Controllers feed Models (game state) to Views (UI windows + prefabs).
- Singleton GameManager: coordinates loop.
- Object pooling and resource management via helper classes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Unity Editor & Settings
    subgraph "Unity Editor / Entry Point"
        Editor["Unity Editor & Project Settings"]:::code
    end

    %% Asset Pipeline
    subgraph "Asset Pipeline"
        Textures["Textures"]:::asset
        Shaders["Shaders"]:::asset
        Materials["Materials"]:::asset
        Prefabs["Prefabs"]:::asset
        ThirdParty1["Priority Queue"]:::ext
        ThirdParty2["TextMesh Pro"]:::ext
    end

    %% Definitions & Data
    subgraph "Definitions & Data"
        DefsLoader["DefsLoader"]:::code
        Definitions["Definitions Data Store"]:::data
    end

    %% Core Simulation
    subgraph "Core Simulation"
        GameManager["GameManager / Core Loop"]:::code
        subgraph "Simulation Components"
            WorldGen["World Generation\n(Map, Grids)"]:::code
            EntitySystem["Entity System\n(Entities, Tick)"]:::code
        end
    end

    %% AI & Character System
    subgraph "AI & Character System"
        AI["AI & Tasks"]:::code
        Characters["Character System"]:::code
    end

    %% Controllers & UI
    subgraph "Controllers & UI"
        Controllers["Input & Controllers"]:::code
        UIWindows["UI Windows & Panels"]:::code
    end

    %% Rendering & Visuals
    subgraph "Rendering & Visuals"
        Visuals["Rendering & Visuals"]:::code
    end

    %% External Tools
    subgraph "External Tools"
        PythonUtils["PythonUtils"]:::ext
    end

    %% Connections
    Editor -->|"loads assets"| Textures
    Editor --> Shaders
    Editor --> Materials
    Editor --> Prefabs
    Editor --> ThirdParty1
    Editor --> ThirdParty2

    Textures -->|"resources for"| WorldGen
    Shaders --> WorldGen
    Materials --> Visuals
    Prefabs --> UIWindows

    DefsLoader -->|"loads data"| Definitions
    Definitions -->|"used by"| WorldGen
    Definitions --> EntitySystem

    WorldGen -->|"initializes"| EntitySystem
    EntitySystem -->|"ticks"| GameManager
    GameManager --> WorldGen
    GameManager --> EntitySystem

    EntitySystem --> Characters
    EntitySystem --> AI
    AI --> Characters
    Characters -->|"commands"| EntitySystem

    Controllers -->|"user input → events"| GameManager
    Controllers --> UIWindows
    UIWindows --> Controllers

    GameManager --> Visuals
    WorldGen --> Visuals
    EntitySystem --> Visuals

    PythonUtils -.->|"offline scripts"| Definitions
    PythonUtils -.-> WorldGen

    %% Click Events
    click Editor "https://github.com/fy-/fyworld/tree/master/FyWorld/ProjectSettings/"
    click Textures "https://github.com/fy-/fyworld/tree/master/FyWorld/Assets/Fy/Resources/Textures/"
    click Shaders "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Resources/Shaders/*.shader"
    click Materials "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Resources/Materials/grounds.mat"
    click Prefabs "https://github.com/fy-/fyworld/tree/master/FyWorld/Assets/Fy/Resources/Prefabs/UI/"
    click ThirdParty1 "https://github.com/fy-/fyworld/tree/master/FyWorld/Assets/Priority Queue/"
    click ThirdParty2 "https://github.com/fy-/fyworld/tree/master/FyWorld/Assets/TextMesh Pro/"
    click WorldGen "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/World/GroundGrid.cs"
    click EntitySystem "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Entities/Ground.cs"
    click DefsLoader "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Definitions/DefsLoader*.cs"
    click GameManager "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Game/GameManager.cs"
    click Characters "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Characters/BaseCharacter.cs"
    click AI "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Characters/AI/BrainNode.cs"
    click Controllers "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Controllers/TileSelectorController.cs"
    click UIWindows "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Controllers/UI/MenuController.cs"
    click Visuals "https://github.com/fy-/fyworld/blob/master/FyWorld/Assets/Fy/Scripts/Visuals/BucketRenderer.cs"
    click PythonUtils "https://github.com/fy-/fyworld/blob/master/PythonUtils/connected.py"

    %% Styles
    classDef code fill:#cce5ff,stroke:#3366ff,color:#000;
    classDef asset fill:#d4edda,stroke:#28a745,color:#000;
    classDef ext fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#000;
```
