How mafiahub/mafiaunity works
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