# icetheys/rust-mta architecture

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

- Interactive diagram: https://gitdiagram.com/icetheys/rust-mta
- Repository: https://github.com/icetheys/rust-mta

## Overview

1. This is an MTA:SA server repository, not a generic app. The root contains the server runtime configuration and persistence files: `mtaserver.conf`, `acl.xml`, `banlist.xml`, `settings.xml`, `vehiclecolors.conf`, plus `registry.db` and `server-id.keys`. The architecture is therefore resource-based Lua scripts deployed into an MTA server.

2. The main game logic lives in `resources/[STONEAGE]/gamemode`. This is the authoritative core of the project and is split the MTA way: client scripts for UI/rendering/input, server scripts for game rules and persistence, and `global/` modules for shared data/configuration. It is the central subsystem that orchestrates the rest of the resources.

3. The gamemode’s client side handles player-facing presentation and local interaction: HUD, main menu, inventory, tutorials, weapon visuals, damage/death feedback, temporary effects, and UI utilities. The server side handles the real game state: accounts, player state, inventory, crafting, damage, chat, attachments, furnaces, planting, research tables, and other system logic.

4. Persistence is server-owned. `gamemode/scripts/server/database/` plus the separate `stoneage_sql` resource indicate a dedicated data layer for accounts and world objects, with permanent state likely stored through the MTA database stack and `registry.db`. Clients do not access persistence directly; they request actions that the server validates and saves.

5. The survival/crafting loop is implemented as a set of cooperating gameplay resources: `stoneage_farms`, `stoneage_pickups`, `stoneage_recycler`, `stoneage_base_building`, `stoneage_sentrys`, `stoneage_vehicles`, `stoneage_gas_stations`, `stoneage_hospitals`, `stoneage_faint`, and the crafting/furnace/research code inside the gamemode. Flow-wise, players gather resources, process them, craft items, build structures, and use the resulting equipment in the world.

6. The world is authored as separate map resources under `resources/[STONEAGE]/[dependencies]/stoneage_maps` and related editor dumps/backups. These resources place islands, walls, patrol/loot points, spawn zones, and military areas. Some include map editor scripting extensions and LOD streaming helpers, so static world content is packaged independently from gameplay logic.

7. Large parts of the visual world are injected through an asset replacement layer. The `replaces` resource ships encrypted DFF/TXD/COL assets for animals, weapons, pickups, bases, skins, objects, and vehicles. This means the rendered game content is decoupled from gameplay scripts and is delivered as streamed model/texture replacements.

8. UI and interaction are split into reusable framework resources instead of being embedded in the gamemode. Examples include `stoneage_ui` (widget toolkit), `stoneage_interaction` (context/option lists), `stoneage_notifications`, `stoneage_scoreboard`, `stoneage_nametag`, `stoneage_compass`, `stoneage_loadscreen`, `stoneage_object_preview`, `stoneage_highlight`, `stoneage_zoom`, and `texNames`. These are presentation-only or near-presentation subsystems used by the main game mode.

9. Administrative and operational controls are isolated in `stoneage_admin`, `stoneage_ac`, `stoneage_logs`, `stoneage_settings`, `stoneage_ranking`, and `richpresence-id`. Admin features include bans, spectate, fly mode, inventory edits, VIP/group management, and command handling. Logging is also an explicit subsystem, with server-side log handling and a Discord integration path in `stoneage_logs`.

10. Vehicle and transport mechanics are their own cluster. `stoneage_vehicles`, `stoneage_enter_vehicle`, `stoneage_bike`, `_stoneage_ship`, and `stoneage_helicopter` handle ownership/repair/engine behavior and transport-specific interactions, while `stoneage_gas_stations` ties vehicle usage to fuel/economy. This keeps vehicle logic outside the core survival and building code.

11. There are several auxiliary gameplay services that plug into the main loop rather than own it: `dep-npc` for NPC AI/tasks, `stoneage_radiation_zones` for environmental hazards, `stoneage_airdrop` for loot events, `stoneage_military` for gated military-area behavior, and `stoneage_voice`/`stoneage_sound3D` for immersive audio. These are event-driven support systems.

12. Overall data flow is client action → server authority → persistence/world update → broadcast back to clients. Most features are resource-isolated, connected through MTA resource metadata, shared Lua modules, and event/export-style integration. For an architecture diagram, the biggest boundary is between the central gamemode/server systems and the many independent support resources around it.

Main entry points: [`resources/[STONEAGE]/gamemode/scripts/server`](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/server) (Server side), [`resources/[STONEAGE]/gamemode/scripts/client`](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/client) (Client side), [`resources/[STONEAGE]/gamemode`](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode) (Core mode), [`resources/[STONEAGE]/[dependencies]/stoneage_ac`](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_ac) (Anti-cheat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Server root"]
  node_server_root[("Server files<br/>mta config/persistence")]
end

subgraph group_gamemode["Gamemode"]
  node_gamemode_core["Core mode<br/>main gameplay"]
  node_gm_client["Client side<br/>presentation/input"]
  node_gm_server["Server side<br/>authority/state"]
  node_gm_shared["Shared data<br/>config/shared modules"]
  node_gm_db["Game DB<br/>persistence layer"]
  node_stoneage_crafting["Craft loop<br/>crafting/process"]
end

subgraph group_world["World content"]
  node_stoneage_world["World maps<br/>static map resources"]
end

subgraph group_ui["UI/interaction"]
  node_stoneage_ui["UI toolkit<br/>widget framework"]
  node_stoneage_interaction["Interaction<br/>context actions"]
  node_stoneage_notifications["Notifications<br/>message UI"]
  node_stoneage_scoreboard["Scoreboard<br/>player list UI"]
end

subgraph group_systems["Gameplay systems"]
  node_stoneage_sql[("SQL resource<br/>database service")]
  node_stoneage_vehicles["Vehicles<br/>transport mechanics"]
  node_stoneage_base_building["Base building<br/>building system"]
  node_stoneage_survival["Survival loop<br/>resource gathering"]
  node_dep_npc["NPC AI<br/>npc runtime"]
  node_stoneage_audio["Audio support<br/>sound/voice"]
end

subgraph group_ops["Ops/admin"]
  node_stoneage_admin["Admin panel<br/>administration"]
  node_stoneage_ac["Anti-cheat<br/>protection"]
  node_stoneage_logs["Logs<br/>logging/discord"]
  node_stoneage_settings["Settings"]
end

subgraph group_assets["Assets/replacements"]
  node_replaces["Asset replaces<br/>streamed models/textures"]
end

node_server_root -->|"boots"| node_gamemode_core
node_gamemode_core -->|"splits"| node_gm_client
node_gamemode_core -->|"splits"| node_gm_server
node_gamemode_core -->|"shares"| node_gm_shared
node_gm_server -->|"persists"| node_gm_db
node_gm_db -->|"uses"| node_stoneage_sql
node_gm_server -->|"runs"| node_stoneage_crafting
node_gm_server -->|"orchestrates"| node_stoneage_survival
node_gm_server -->|"authorizes"| node_stoneage_vehicles
node_gm_server -->|"authorizes"| node_stoneage_base_building
node_gm_client -->|"renders"| node_stoneage_ui
node_gm_client -->|"opens"| node_stoneage_interaction
node_gm_client -->|"shows"| node_stoneage_notifications
node_gm_client -->|"shows"| node_stoneage_scoreboard
node_gm_server -->|"spawns"| node_stoneage_world
node_gm_shared -->|"references"| node_replaces
node_stoneage_crafting -.->|"visualizes"| node_replaces
node_stoneage_survival -->|"places"| node_stoneage_world
node_stoneage_admin -->|"controls"| node_gm_server
node_stoneage_ac -.->|"checks"| node_gm_client
node_stoneage_ac -->|"checks"| node_gm_server
node_stoneage_logs -->|"records"| node_gm_server
node_stoneage_settings -->|"configures"| node_gm_client
node_dep_npc -->|"operates in"| node_stoneage_world
node_stoneage_audio -->|"plays"| node_gm_client

click node_gamemode_core "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode"
click node_gm_client "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/client"
click node_gm_server "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/server"
click node_gm_shared "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/global"
click node_gm_db "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/server/database"
click node_stoneage_sql "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_sql"
click node_stoneage_vehicles "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_vehicles"
click node_stoneage_base_building "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_base_building"
click node_replaces "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/replaces"
click node_stoneage_ui "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_ui"
click node_stoneage_interaction "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_interaction"
click node_stoneage_notifications "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_notifications"
click node_stoneage_scoreboard "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_scoreboard"
click node_stoneage_admin "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_admin"
click node_stoneage_ac "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_ac"
click node_stoneage_logs "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_logs"
click node_stoneage_settings "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_settings"
click node_dep_npc "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/dep-npc"
click node_stoneage_audio "https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_sound3D"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_root,node_replaces toneBlue
class node_gamemode_core,node_gm_client,node_gm_server,node_gm_shared,node_gm_db,node_stoneage_crafting toneAmber
class node_stoneage_world toneMint
class node_stoneage_ui,node_stoneage_interaction,node_stoneage_notifications,node_stoneage_scoreboard toneRose
class node_stoneage_sql,node_stoneage_vehicles,node_stoneage_base_building,node_stoneage_survival,node_dep_npc,node_stoneage_audio toneIndigo
class node_stoneage_admin,node_stoneage_ac,node_stoneage_logs,node_stoneage_settings toneTeal
```

## Components

### Server root

MTA server configuration and persistence files at the repository root.

- **Server files**: mta config/persistence · Top-level MTA server configuration, ACL, bans, settings, and local persistence files.

### Gamemode

Authoritative StoneAge game logic and shared data.

- [Core mode](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode): main gameplay · Central StoneAge gamemode coordinating client, server, and shared modules. · `resources/[STONEAGE]/gamemode`
- [Client side](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/client): presentation/input · Player-facing rendering, HUD, menus, inventory UI, tutorials, and local effects. · `resources/[STONEAGE]/gamemode/scripts/client`
- [Server side](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/server): authority/state · Server-owned game rules, player state, inventory, crafting, damage, chat, and world interactions. · `resources/[STONEAGE]/gamemode/scripts/server`
- [Shared data](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/global): config/shared modules · Global gameplay configs, object definitions, blueprints, utilities, and spawn positions. · `resources/[STONEAGE]/gamemode/scripts/global`
- [Game DB](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/gamemode/scripts/server/database): persistence layer · Gamemode database access for accounts and persisted world objects. · `resources/[STONEAGE]/gamemode/scripts/server/database`
- **Craft loop**: crafting/process · Crafting, furnaces, research tables, and item processing inside the core loop.

### World content

Map resources, editor dumps, and static world placement.

- **World maps**: static map resources · Independent map resources and editor dumps for islands, walls, spawns, patrols, and loot points.

### UI/interaction

Presentation, HUD, and reusable interaction framework resources.

- [UI toolkit](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_ui): widget framework · Reusable widget system and common UI primitives used across the project. · `resources/[STONEAGE]/[dependencies]/stoneage_ui`
- [Interaction](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_interaction): context actions · Option lists and contextual interaction rendering for world objects and players. · `resources/[STONEAGE]/[dependencies]/stoneage_interaction`
- [Notifications](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_notifications): message UI · Client/server notification delivery for player feedback. · `resources/[STONEAGE]/[dependencies]/stoneage_notifications`
- [Scoreboard](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_scoreboard): player list UI · Scoreboard presentation and server-fed player information. · `resources/[STONEAGE]/[dependencies]/stoneage_scoreboard`

### Gameplay systems

Survival, crafting, vehicles, hazards, and auxiliary gameplay services.

- [SQL resource](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_sql): database service · Dedicated database resource used by the gamemode and other systems. · `resources/[STONEAGE]/[dependencies]/stoneage_sql`
- [Vehicles](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_vehicles): transport mechanics · Vehicle ownership, repair, engine behavior, and vehicle persistence/logic. · `resources/[STONEAGE]/[dependencies]/stoneage_vehicles`
- [Base building](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_base_building): building system · Structure placement, upgrades, sync, and base-building rules. · `resources/[STONEAGE]/[dependencies]/stoneage_base_building`
- **Survival loop**: resource gathering · Farms, pickups, recycler, sentries, hospitals, fainting, and gas stations that feed progression.
- [NPC AI](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/dep-npc): npc runtime · NPC control, tasks, and behavior helpers for non-player characters. · `resources/[STONEAGE]/[dependencies]/dep-npc`
- [Audio support](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_sound3D): sound/voice · 3D sound and voice resources used for immersion and proximity audio. · `resources/[STONEAGE]/[dependencies]/stoneage_sound3D`

### Ops/admin

Administration, anti-cheat, logging, settings, and rankings.

- [Admin panel](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_admin): administration · Bans, spectate, fly mode, inventory edits, VIP/group management, and commands. · `resources/[STONEAGE]/[dependencies]/stoneage_admin`
- [Anti-cheat](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_ac): protection · Client/server anti-cheat checks and kick-ping enforcement. · `resources/[STONEAGE]/[dependencies]/stoneage_ac`
- [Logs](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_logs): logging/discord · Server logging with Discord integration path. · `resources/[STONEAGE]/[dependencies]/stoneage_logs`
- [Settings](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/stoneage_settings): player settings · Per-player settings UI and persistence-facing settings resource. · `resources/[STONEAGE]/[dependencies]/stoneage_settings`

### Assets/replacements

Streamed models, textures, sounds, and visual replacement layers.

- [Asset replaces](https://github.com/icetheys/rust-mta/tree/main/resources/[STONEAGE]/[dependencies]/replaces): streamed models/textures · Encrypted DFF/TXD/COL replacements for objects, weapons, pickups, skins, animals, horses, and vehicles. · `resources/[STONEAGE]/[dependencies]/replaces`

## Connections

- Server files → Core mode: boots · Server starts the central gamemode resource.
- Core mode → Client side: splits · Client presentation is one half of the gamemode.
- Core mode → Server side: splits · Server authority and state management form the other half.
- Core mode → Shared data: shares · Shared configs, objects, and utilities feed both sides.
- Server side → Game DB: persists · Server logic writes account and world state through the gamemode data layer.
- Game DB → SQL resource: uses · Dedicated SQL resource backs persistence operations.
- Server side → Craft loop: runs · Crafting, furnace, and research logic is controlled server-side.
- Server side → Survival loop: orchestrates · Core server logic coordinates survival and resource-processing resources.
- Server side → Vehicles: authorizes · Vehicle mechanics are validated and managed by server resources.
- Server side → Base building: authorizes · Building placement and upgrades are governed by the server.
- Client side → UI toolkit: renders · Client gameplay UI is built on the shared widget toolkit.
- Client side → Interaction: opens · Context actions and option lists surface player interactions.
- Client side → Notifications: shows · Client displays server-driven notifications.
- Client side → Scoreboard: shows · Client renders scoreboard state.
- Server side → World maps: spawns · Game logic consumes authored map resources and spawn zones.
- Shared data → Asset replaces: references · Shared object/item definitions align with streamed replacement assets.
- Craft loop → Asset replaces: visualizes · Craftable items and placeables use replacement models and textures.
- Survival loop → World maps: places · Gathering points, loot points, and hazard zones live in map resources.
- Admin panel → Server side: controls · Admin operations manipulate server-managed state.
- Anti-cheat → Client side: checks · Anti-cheat includes client-side enforcement hooks.
- Anti-cheat → Server side: checks · Server-side enforcement detects and reacts to abuse.
- Logs → Server side: records · Server events and administrative actions are logged.
- Settings → Client side: configures · Player settings are exposed through client UI.
- NPC AI → World maps: operates in · NPC tasks and behaviors run against authored world locations.
- Audio support → Client side: plays · Voice and 3D sounds are presented to players on the client.
