# adskdev/random_asylum_addon architecture

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

- Interactive diagram: https://gitdiagram.com/adskdev/random_asylum_addon
- Repository: https://github.com/adskdev/random_asylum_addon

## Overview

#### Purpose and Runtime
Random Asylum is a server-hosted Garry’s Mod gamemode focused on timed, round-based deathmatch where players receive random scripted weapons (SWEPs) whenever they spawn. It runs in Garry’s Mod’s Lua gamemode lifecycle, with separate server, client, and shared loading paths.

Entry metadata and gamemode registration are in:
- `addon.json`
- `gamemodes/randomasylum/randomasylum.txt`
- `gamemodes/randomasylum/gamemode/shared.lua`

#### Bootstrap and Realm Separation
The gamemode’s load boundary follows Garry’s Mod conventions: server initialization establishes authoritative gameplay logic, client initialization loads presentation code, and shared definitions bridge both realms.

- Server bootstrap: `gamemodes/randomasylum/gamemode/init.lua`
- Client bootstrap: `gamemodes/randomasylum/gamemode/cl_init.lua`
- Shared gamemode definition: `gamemodes/randomasylum/gamemode/shared.lua`

This separation is central: rounds, spawning, weapon assignment, and player state are server-authoritative; HUD rendering is client-side.

#### Round Lifecycle Controller
Round management is the primary control-flow coordinator. It governs waiting/start/end transitions, round duration, and minimum-player gating using server-configurable ConVars. At round completion it initiates map voting rather than implementing map selection internally.

- `gamemodes/randomasylum/gamemode/round_management.lua`
- `gamemodes/randomasylum/gamemode/init.lua`

Expected flow: server waits for enough players, starts a timed round, tracks its progress, ends the round, presents results, and hands off to MapVote for map transition.

#### Spawn and Random Weapon Distribution
The weapon subsystem applies the core game rule at player spawn: select eligible SWEPs from the server’s installed weapon collection and grant the configured count. It filters banned utility weapons and conditionally permits admin-only weapons.

- `gamemodes/randomasylum/gamemode/weapon_system.lua`
- `gamemodes/randomasylum/gamemode/init.lua`

This is an integration boundary with arbitrary installed SWEP addons: the gamemode consumes their registered weapon definitions but does not own their behavior.

#### Player State, Statistics, and Appearance
Per-player gameplay state includes round kills and deaths, which feed round results and HUD status. Appearance handling is isolated from combat and provides an admin-controlled model-change command.

- `gamemodes/randomasylum/gamemode/player_appearance.lua`
- `gamemodes/randomasylum/gamemode/round_management.lua`

The player model command is an administrative server control path, distinct from automatic spawn/round processing.

#### Client HUD and Results Presentation
The custom HUD is the client-facing projection of round state: remaining time, active-player information, and end-of-round results. It depends on state replicated or exposed from server-side round management rather than owning game decisions.

- `gamemodes/randomasylum/gamemode/hud_system.lua`
- `gamemodes/randomasylum/gamemode/cl_init.lua`

Killfeed behavior is deliberately external; the recommended Advanced Killfeed addon supplies that presentation concern.

#### External Dependencies and Operations
Garry’s Mod provides the Lua runtime, hooks, player/weapon APIs, ConVars, and networking facilities. The gamemode is distributed as a Steam Workshop addon and expects server operators to configure ConVars via console or `server.cfg`.

Map rotation depends on the external MapVote addon, invoked automatically after rounds. Optional audio, death-sound, spawn-protection, and killfeed addons augment behavior but are not part of the gamemode’s core architecture.

Main entry points: [`gamemodes/randomasylum/gamemode/round_management.lua`](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/round_management.lua) (Round Controller), [`gamemodes/randomasylum/gamemode/init.lua`](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/init.lua) (Server Bootstrap), [`gamemodes/randomasylum/gamemode/shared.lua`](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/shared.lua) (Shared Definition), [`gamemodes/randomasylum/gamemode/cl_init.lua`](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/cl_init.lua) (Client Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Gamemode Loading"]
  node_addon["Addon Metadata<br/>addon manifest<br/>[addon.json]"]
  node_registration["Gamemode Registration<br/>gamemode manifest<br/>[randomasylum.txt]"]
  node_shared["Shared Definition<br/>shared Lua<br/>[shared.lua]"]
  node_server_bootstrap["Server Bootstrap<br/>server Lua<br/>[init.lua]"]
  node_client_bootstrap["Client Bootstrap<br/>client Lua<br/>[cl_init.lua]"]
end

subgraph group_gameplay["Server Gameplay"]
  node_rounds["Round Controller<br/>server lifecycle"]
  node_player_state["Round Player State<br/>player stats"]
  node_weapons["Random Weapon System<br/>server spawn system<br/>[weapon_system.lua]"]
  node_appearance["Player Appearance<br/>server admin command"]
end

subgraph group_presentation["Client Presentation"]
  node_hud["HUD and Results<br/>client HUD<br/>[hud_system.lua]"]
end

node_gmod{{"Garry's Mod Runtime"}}
node_sweps[("Installed SWEP Addons<br/>external weapon registry")]
node_mapvote{{"MapVote Addon<br/>external map rotation"}}
node_operators(("Server Operators<br/>operations"))

node_addon -->|"packages"| node_registration
node_registration -->|"registered with"| node_gmod
node_gmod -->|"server lifecycle"| node_server_bootstrap
node_gmod -->|"client lifecycle"| node_client_bootstrap
node_gmod -->|"shared lifecycle"| node_shared
node_server_bootstrap -->|"loads"| node_rounds
node_server_bootstrap -->|"loads"| node_weapons
node_server_bootstrap -->|"loads"| node_appearance
node_client_bootstrap -->|"loads"| node_hud
node_shared -.->|"bridges realm"| node_server_bootstrap
node_shared -.->|"bridges realm"| node_client_bootstrap
node_operators -->|"configure ConVars"| node_rounds
node_rounds -->|"tracks"| node_player_state
node_rounds -->|"drives spawn flow"| node_weapons
node_weapons -->|"selects from"| node_sweps
node_rounds -->|"starts after round"| node_mapvote
node_rounds -.->|"replicates round state"| node_hud
node_player_state -.->|"exposes stats"| node_hud

click node_addon "https://github.com/adskdev/random_asylum_addon/blob/master/addon.json"
click node_registration "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/randomasylum.txt"
click node_shared "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/shared.lua"
click node_server_bootstrap "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/init.lua"
click node_client_bootstrap "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/cl_init.lua"
click node_rounds "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/round_management.lua"
click node_weapons "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/weapon_system.lua"
click node_appearance "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/player_appearance.lua"
click node_hud "https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/hud_system.lua"

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_addon,node_registration,node_shared,node_server_bootstrap,node_client_bootstrap toneBlue
class node_rounds,node_player_state,node_weapons,node_appearance toneAmber
class node_hud toneMint
class node_gmod,node_sweps,node_mapvote,node_operators toneNeutral
```

## Components

### Gamemode Loading

Garry’s Mod loads separate server, client, and shared paths.

- [Addon Metadata](https://github.com/adskdev/random_asylum_addon/blob/master/addon.json): addon manifest · `addon.json`
- [Gamemode Registration](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/randomasylum.txt): gamemode manifest · `gamemodes/randomasylum/randomasylum.txt`
- [Shared Definition](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/shared.lua): shared Lua · Definitions loaded in both server and client realms. · `gamemodes/randomasylum/gamemode/shared.lua`
- [Server Bootstrap](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/init.lua): server Lua · Loads authoritative gameplay systems. · `gamemodes/randomasylum/gamemode/init.lua`
- [Client Bootstrap](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/cl_init.lua): client Lua · Loads client presentation code. · `gamemodes/randomasylum/gamemode/cl_init.lua`

### Server Gameplay

Authoritative round and spawn behavior.

- [Round Controller](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/round_management.lua): server lifecycle · Gates, times, starts, and ends deathmatch rounds. · `gamemodes/randomasylum/gamemode/round_management.lua`
- **Round Player State**: player stats · Tracks per-player round kills and deaths for results and HUD.
- [Random Weapon System](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/weapon_system.lua): server spawn system · Selects eligible SWEPs and grants the configured count on spawn. · `gamemodes/randomasylum/gamemode/weapon_system.lua`
- [Player Appearance](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/player_appearance.lua): server admin command · Provides an admin-controlled player-model change path. · `gamemodes/randomasylum/gamemode/player_appearance.lua`

### Client Presentation

Client-side view of replicated round state.

- [HUD and Results](https://github.com/adskdev/random_asylum_addon/blob/master/gamemodes/randomasylum/gamemode/hud_system.lua): client HUD · Renders timer, active-player status, and round results. · `gamemodes/randomasylum/gamemode/hud_system.lua`

### Other components

- **Garry's Mod Runtime**: runtime · Provides Lua lifecycle, hooks, APIs, ConVars, and networking.
- **Installed SWEP Addons**: external weapon registry · Registered weapon definitions consumed by the gamemode.
- **MapVote Addon**: external map rotation · Selects the next map after a completed round.
- **Server Operators**: operations · Configure gameplay ConVars through console or server.cfg.

## Connections

- Addon Metadata → Gamemode Registration: packages
- Gamemode Registration → Garry's Mod Runtime: registered with
- Garry's Mod Runtime → Server Bootstrap: server lifecycle
- Garry's Mod Runtime → Client Bootstrap: client lifecycle
- Garry's Mod Runtime → Shared Definition: shared lifecycle
- Server Bootstrap → Round Controller: loads
- Server Bootstrap → Random Weapon System: loads
- Server Bootstrap → Player Appearance: loads
- Client Bootstrap → HUD and Results: loads
- Shared Definition → Server Bootstrap: bridges realm
- Shared Definition → Client Bootstrap: bridges realm
- Server Operators → Round Controller: configure ConVars
- Round Controller → Round Player State: tracks
- Round Controller → Random Weapon System: drives spawn flow
- Random Weapon System → Installed SWEP Addons: selects from
- Round Controller → MapVote Addon: starts after round
- Round Controller → HUD and Results: replicates round state
- Round Player State → HUD and Results: exposes stats