# mafiahub/mafiaunity architecture

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

- Interactive diagram: https://gitdiagram.com/mafiahub/mafiaunity
- Repository: https://github.com/mafiahub/mafiaunity

## Overview

##### Project type and purpose
- This is an open-source Unity-based framework (“MafiaUnity”) that re-implements the original Mafia: The City of Lost Heaven game engine in modern tech.
- It provides tools for importing native Mafia asset formats, a modding API, an in-engine editor extension, and the full game runtime (scenes, controllers, rendering, UI).

##### File structure
- Top-level:
– Assets/ : all Unity assets—Scripts, Prefabs, Resources, Scenes, Plugins, Standard Assets
– StreamingAssets/Mods : mod bundles and entry points
– Docs/ : documentation on data formats and mod structure
– Tools/ : build scripts
– ProjectSettings/Packages : Unity project configuration
- Assets/Scripts substructure reveals key modules:
– API: format conversion and native format loaders
– Core: FileSystem, GameAPI, Managers (Console, Cvar, Mission, Mod)
· Core/Modding: dynamic C# compiler, IModScript interface
– Editor: Unity editor extensions (solution generation, mod manager GUI)
– Game: domain logic—controllers, game main, HUD, mission hacks, object factory
– Rendering: custom shaders, billboard logic, post-FX setup, animation players
– Internal: low-level asset loaders (BMP, OGG, WAV, TGALoader), scene/model generators
– Helpers / Utils / Tools: assorted utility classes (threaded jobs, camera extensions, object injection)
- Third-Party: AssetBundle Browser, NVorbis (Ogg/Vorbis decoder), command_terminal
- StreamingAssets: runtime mod discovery, JSON mod definitions, asset bundle manifests
- Scenes: ModelViewer, Game, Playground

##### README for additional insights
- Purpose: use original .dta files, unpack assets, plug into Unity
- Architecture hints: separation of importing pipeline, runtime framework, editor tooling, modding API
- Dependencies: Unity 2019.3.9f1, native game data

a. Main components:
– Unity Editor & Build Pipeline
– Asset Import Pipeline: .dta unpacker → API/MafiaFormats loaders → Unity Assets/StreamingAssets
– Core Framework at runtime:
· FileSystem & GameAPI
· Managers (Console, Cvar, Mission, Mod)
· Modding Subsystem (dynamic compile, IModScript host)
– Game Logic Layer: controllers, object factory, mission hacks, player/human, HUD, music manager
– Rendering Engine: shaders, model definition, animation players, post-FX
– External Services/Third-Party Libraries: NVorbis, AssetBundle Browser, command_terminal
– Tools & Editor Extensions: solution generation, mod manager GUI, object injector
– Data Storage: StreamingAssets/Mods (JSON, Bundles), Resources (materials, flares, dummies)
b. Relationships and interactions:
– Editor extensions feed into Build Pipeline → creates asset bundles in StreamingAssets
– On startup, FileSystem + GameAPI load unpacked data via API loaders
– Managers coordinate runtime state and dispatch cross-component events
– ModManager loads mod entry points (IModScript) and invokes them within GameAPI context
– Rendering layer subscribes to GameLogic state and draws meshes/shaders
– Internal loaders can be invoked both at import time and runtime (for dynamic loads)
c. Architectural patterns & design principles:
– Modular layering: Import → Core API → Game Logic → Rendering
– Plugin architecture for mods (dynamic C# compilation, IModScript)
– Component-based Unity design (monobehaviours for controllers, GUI, editors)
– Separation of Editor vs Runtime code (Assets/Scripts/Editor vs /Game)
d. Key technologies & libraries:
– Unity 2019.3.9f1
– C# (Boo for some plugins), UnityAssetBundleBrowser, NVorbis Ogg decoder
– Custom dynamic C# compiler (Roslyn-based drivers)

##### Detail
- Data formats (.dta → unpacked assets → MafiaFormatLoader → Unity asset types)
- Dynamic compile pipeline (Roslyn drivers) as its own component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Editor and Import Layer
    subgraph "Editor & Import (Build Pipeline)"
        direction TB
        Editor["Unity Editor & Build Pipeline"]:::editor
        subgraph "Asset Import Pipeline"
            direction TB
            API["API: Format Conversions & Loaders\n(Assets/Scripts/API)"]:::import
            MafiaFormats["MafiaFormats\n(Assets/Scripts/API/MafiaFormats)"]:::import
            Internal["Internal Loaders\n(BMP, OGG, WAV, TGALoader\nAssets/Scripts/Internal)"]:::import
        end
    end

    %% Data Storage
    Mods["StreamingAssets/Mods (Runtime Mods & Bundles)"]:::storage

    %% Runtime Core & Managers
    subgraph "Core & Managers"
        direction TB
        FileSystem["FileSystem"]:::core
        GameAPI["GameAPI"]:::core
        Managers["Managers\n(Console, Cvar, Mission,\nMod)"]:::managers
        Modding["Modding Subsystem\n(Dynamic Compiler,\nIModScript)"]:::managers
    end

    %% Game Logic Layer
    subgraph "Game Logic Layer"
        direction TB
        GameLogic["Game Logic"]:::game
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        direction TB
        Rendering["Rendering Engine\n(Shaders, Animation Players,\nPost-FX, Billboards)"]:::render
    end

    %% Tools & Utilities
    subgraph "Tools & Editor Extensions"
        direction TB
        Tools["Tools & Editor Extensions\n(Assets/Scripts/Tools)"]:::utils
        Utils["Utility Classes\n(Assets/Scripts/Utils)"]:::utils
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        direction TB
        Third["AssetBundle Browser,\nNVorbis, command_terminal"]:::third
    end

    %% Scenes
    subgraph "Scenes"
        direction TB
        Scenes["Scenes\n(Game, ModelViewer, Playground)"]:::scenes
    end

    %% Connections
    Editor -->|builds| API
    API --> MafiaFormats
    API --> Internal
    Editor -->|outputs bundles| Mods

    Scenes -->|loads on startup| FileSystem
    Mods -->|runtime discovery| FileSystem

    FileSystem -->|provides data| GameAPI
    GameAPI -->|initializes| Managers
    Managers -->|manages state| GameLogic
    Modding -->|injects scripts into| GameAPI
    GameLogic -->|feeds state to| Rendering

    Tools -->|assist| Editor
    Utils -->|support| GameLogic

    Third -->|used by| API
    Third -->|used by| Rendering

    %% Click Events
    click Editor "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Editor"
    click API "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/API"
    click MafiaFormats "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/API/MafiaFormats"
    click Internal "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Internal"
    click Mods "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/StreamingAssets/Mods"
    click FileSystem "https://github.com/mafiahub/mafiaunity/blob/develop/Assets/Scripts/Core/FileSystem.cs"
    click GameAPI "https://github.com/mafiahub/mafiaunity/blob/develop/Assets/Scripts/Core/GameAPI.cs"
    click Managers "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Core/Managers"
    click Modding "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Core/Modding"
    click Tools "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Tools"
    click Utils "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scripts/Utils"
    click Third "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Third Party Assets"
    click Scenes "https://github.com/mafiahub/mafiaunity/tree/develop/Assets/Scenes"

    %% Styles
    classDef editor fill:#D0E7FF,stroke:#1E70BF,color:#1E70BF;
    classDef import fill:#E0F8E0,stroke:#2E8B57,color:#2E8B57;
    classDef core fill:#E6FFE6,stroke:#009900,color:#006600;
    classDef managers fill:#CCFFCC,stroke:#339933,color:#006600;
    classDef game fill:#FFE5B4,stroke:#FF8C00,color:#CC5500;
    classDef render fill:#ECD9FF,stroke:#8A2BE2,color:#551A8B;
    classDef utils fill:#D9F0FF,stroke:#3399CC,color:#006680;
    classDef storage fill:#FFF2CC,stroke:#CC9900,color:#996600;
    classDef third fill:#F0F0F0,stroke:#808080,color:#505050;
    classDef scenes fill:#FFD9E6,stroke:#FF69B4,color:#C71585;
```
