# exmod-team/exiled architecture

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

- Interactive diagram: https://gitdiagram.com/exmod-team/exiled
- Repository: https://github.com/exmod-team/exiled

## Overview

EXILED is a modular .NET modding framework for SCP: Secret Laboratory. Architecturally, it is not a single application but a solution composed of runtime libraries, a plugin loader, feature modules, and supporting tooling/documentation. The repository is organized around one central idea: intercept the game’s internal behaviors at runtime, translate them into a stable event/API surface, and let server plugins consume that surface.

Core architectural boundaries

- Game/runtime boundary: the actual SCP:SL server and its internal classes are external to this repo.
- Hooking/patching boundary: EXILED uses runtime patches to intercept game methods and inject its own event pipeline.
- API boundary: `Exiled.API` exposes game abstractions, utility types, enums, and wrapper objects for plugins.
- Module boundary: feature packages such as custom items, custom roles, permissions, and credit tags are separate assemblies that extend the core framework.
- Loader boundary: `Exiled.Loader` is responsible for discovering, loading, updating, and configuring EXILED and plugin assemblies at runtime.
- Consumer boundary: external server plugins are the downstream consumers; the included `Exiled.Example` project shows intended plugin usage.

Main subsystems

1. Exiled.API
This is the foundational library and the main public surface area for plugin authors.

What it contains:
- Game-domain enums for SCP:SL concepts such as doors, items, effects, zones, roles, damage types, spawn reasons, and many SCP-specific states.
- Wrapper/feature classes that represent live game entities and systems:
  - `Player`, `Role`, `Item`, `Pickup`, `Room`, `Door`, `Generator`, `Warhead`, `Map`, `Server`, `Round`, `Respawn`, `TeslaGate`, `Scp914`, and many others.
- Utility and extension methods for working with game objects and domain types.
- Core abstractions and lightweight framework primitives:
  - custom behavior/state machine types
  - actor/object wrappers
  - pooling helpers
  - user settings objects
  - dynamic event dispatcher infrastructure
- Interfaces used to standardize plugin-facing contracts such as config, translation, world-space, position/rotation, and wrapper semantics.

Architectural role:
- This is the stable API layer that higher-level modules and plugin authors target.
- It shields consumers from raw game internals by presenting typed wrappers and domain concepts.

2. Exiled.Events
This is the event interception and translation layer. It is the most structurally important runtime subsystem.

What it contains:
- Event definitions and event argument types for almost every meaningful game action:
  - player lifecycle, item use, map events, SCP behaviors, server round state, warhead, and many others.
- Harmony-style patch classes under `Patches/` that hook into game methods.
- Handler classes under `Handlers/` that publish the framework events.
- Generic patch helpers and “fix” patches that correct or normalize game behaviors while also exposing hooks.
- Internal utility handlers for lists and state tracking, such as pickups, ragdolls, admin toys, and scene lifecycle.

Architectural role:
- This assembly is the runtime bridge between the SCP:SL game and the EXILED event model.
- A patch triggers a handler, which creates event args and dispatches them to subscribed plugins.
- It also maintains some internal runtime state and applies compatibility fixes where the base game behavior is inconsistent or inconvenient for plugins.

Typical data flow:
- Game engine method executes.
- A patch intercepts the call.
- The corresponding handler converts raw game data into EXILED event args.
- Event subscribers in plugins receive the event and may read or modify outcome.
- In some cases, the patched flow is cancelled or altered based on event state.

Important architectural note:
- This repo contains both “event exposure” patches and “fix” patches. The fixes are not just bug fixes in the usual application sense; they are runtime behavior corrections that preserve a predictable plugin API.

3. Exiled.Loader
This is the bootstrap and runtime management subsystem.

What it contains:
- Entry point logic and loader plugin glue.
- Configuration management and translation management.
- Auto-update support:
  - GitHub API client types under `GHApi/`
  - release models and updater logic
- Multi-admin and plugin priority support.
- Linux permission utilities.
- YAML/config handling helpers and custom converters.

Architectural role:
- The loader is responsible for discovering EXILED runtime components and coordinating startup.
- It likely loads modules, applies configuration, manages version updates, and integrates with the game server’s plugin-loading process.
- It is the operational edge of the system: without the loader, the core API/events are not activated in the server process.

Data flow:
- Server starts.
- Loader initializes configuration, translations, and compatibility settings.
- Loader resolves EXILED assemblies and plugin assemblies.
- Loader checks GitHub releases for updates when applicable.
- Loader passes control to the event and feature assemblies, enabling the modding runtime.

4. Exiled.CustomItems
This module provides a framework for defining custom in-game items.

What it contains:
- Public API for custom item types:
  - custom armor, goggles, grenade, keycard, weapon, and base custom item classes
- Custom item-related event args for ownership changes, upgrades, death, escape, handcuffing, and item transformations.
- Commands for giving, spawning, listing, and inspecting custom items.
- Player/map handlers and patches for inventory visibility behavior.

Architectural role:
- This is a domain extension built on top of the base API and event system.
- It adds a higher-level abstraction that plugin authors can use to define new item behaviors without directly patching the game themselves.
- The command layer acts as an operational interface for admins or server operators.

5. Exiled.CustomRoles
This module provides a framework for custom player roles and abilities.

What it contains:
- `CustomRole`, `CustomAbility`, `PassiveAbility`, `ActiveAbility`, and ability activation infrastructure.
- Parsing and type-discrimination utilities for role definitions.
- Keypress-based activators and enum metadata for ability checks/activation styles.
- Commands to give roles, inspect roles, list roles and abilities, and trigger abilities.
- Player event handlers supporting role lifecycle and ability execution.

Architectural role:
- Like custom items, this is a higher-level plugin framework built atop the core event layer.
- It defines role-centric behavior composition, separating passive effects from active abilities.
- The parser/discriminator types indicate that role definitions may be dynamically loaded or configured from structured data rather than only hard-coded.

6. Exiled.Permissions
This module manages server-side permissions and permission groups.

What it contains:
- Permission/group command set for adding/removing permissions, managing groups, and reloading permission data.
- Permission-related model and extension code.
- A permissions YAML resource.

Architectural role:
- This is a separate operational subsystem for admin/control-plane concerns.
- It supports the broader EXILED server ecosystem by managing authorization state, likely consumed by loader commands, plugins, and other modules.

7. Exiled.CreditTags
This module handles credit/rank tags shown to players.

What it contains:
- Tag/rank domain models and enums.
- Database handler and thread-safe request logic.
- Command to show credit tags.
- Credits event handling.

Architectural role:
- This is a small but distinct feature module that bridges UI/presentation concerns and persistent/tag data retrieval.

8. Exiled.Example
This is not production code; it is the reference consumer.

What it contains:
- Example handlers for player, map, item, SCP, server, and warhead events.
- Example commands and configuration.
- Demonstrates the intended plugin authoring model.

Architectural role:
- It shows how downstream plugins subscribe to the event system and use the API surface.
- It is useful as a consumer boundary example in an architecture diagram.

9. Exiled.Installer
This is a standalone installer utility.

What it contains:
- A program entry point, command settings, and embedded resources.
- Resource markup and installer-specific output.

Architectural role:
- Separate from the runtime server plugin pipeline.
- Its job is operational setup rather than in-game behavior.

Supporting platform/tooling

- Documentation:
  - `docs/` contains DocFX documentation for installation, plugin structure, events, MEC usage, and contributing.
  - `.github/documentation` contains additional getting-started content and localized README variants.
- CI/CD:
  - GitHub Actions workflows cover dev builds, docs generation, release, NuGet publishing, and various maintenance tasks.
- Packaging:
  - `build.ps1` and `packaging.ps1` support build/release artifact creation.
  - `.nuspec` and solution/project files indicate package-oriented distribution.
- Repository governance:
  - code style, editorconfig, ruleset, issue templates, and security/community docs.

How the pieces interact at runtime

1. Server startup
- SCP:SL server starts.
- `Exiled.Loader` initializes and reads configuration/translations.
- Loader resolves EXILED modules and any installed plugins.

2. Runtime instrumentation
- `Exiled.Events` patches game methods.
- Patch classes observe specific engine actions such as player damage, role changes, item usage, map generation, SCP mechanics, and round events.

3. Event publication
- Patches forward context into event args.
- Handlers publish strongly typed EXILED events.
- Plugins, custom items, and custom roles subscribe to these events.

4. Higher-level feature execution
- `Exiled.CustomItems` and `Exiled.CustomRoles` build on the event layer to implement reusable gameplay systems.
- Permission and credit-tag modules support admin state and player metadata.
- The example plugin shows how third-party code sits on top of the framework.

5. Outcome control
- Event consumers can usually inspect or alter behavior, depending on the event.
- Some patches also apply fixes or normalize state after base-game actions.

Suggested diagram boundaries

If you are drawing an architecture diagram, the cleanest separation is:

- External system: SCP:SL game server
- Bootstrap layer: Exiled.Loader
- Instrumentation layer: Exiled.Events
- Public framework layer: Exiled.API
- Feature modules: CustomItems, CustomRoles, Permissions, CreditTags
- Consumer layer: third-party plugins and the included Example project
- Operational tooling: Installer, docs, CI/CD, packaging

The most important data direction is bottom-up from the game engine into EXILED’s patch/event pipeline, then outward to plugins and feature modules. The reverse direction exists as well: plugins and feature modules can modify game state through the API, which ultimately affects the live game server.

In short, EXILED is a runtime modding framework with a layered architecture: loader/bootstrap, patch-based event capture, a stable public API, and optional feature modules built on top for items, roles, permissions, and admin-facing utilities.

Main entry points: [`EXILED/Exiled.API/Exiled.API.csproj`](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.API/Exiled.API.csproj) (API), [`EXILED/Exiled.Events/Events.cs`](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Events/Events.cs) (Events), [`EXILED/Exiled.Loader/Loader.cs`](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Loader/Loader.cs) (Loader), [`EXILED/build.ps1`](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/build.ps1) (Packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Runtime framework"
  loader["Loader<br/>bootstrap/runtime<br/>[Loader.cs]"]
  events["Events<br/>patch/event bridge<br/>[Events.cs]"]
  api["API<br/>public framework<br/>[Exiled.API.csproj]"]
  pluginbase["Plugin base<br/>plugin contract<br/>[Plugin.cs]"]
  corewrap["Wrappers<br/>[Player.cs]"]
  coreinfra["Core infra<br/>runtime primitives<br/>[StateController.cs]"]
  loadergh["Update client<br/>release client<br/>[ApiProvider.cs]"]
  loadercfg["Config system<br/>loader support<br/>[ConfigManager.cs]"]
end

subgraph "Feature modules"
  customitems["Custom items<br/>feature module<br/>[CustomItems.cs]"]
  customroles["Custom roles<br/>feature module<br/>[CustomRoles.cs]"]
  permissions["Permissions<br/>admin module<br/>[Permissions.cs]"]
  credittags["Credit tags<br/>feature module<br/>[CreditTags.cs]"]
end

subgraph "Tooling & docs"
  installer["Installer<br/>setup utility<br/>[Program.cs]"]
  docs["Docs<br/>documentation<br/>[docfx.json]"]
  ci["GitHub Actions<br/>automation<br/>[main.yml]"]
  packaging["Packaging<br/>release tooling<br/>[build.ps1]"]
end

subgraph "Consumer example"
  example["Example plugin<br/>reference consumer<br/>[Example.cs]"]
end

game[("SCP:SL server<br/>external game runtime")]

game -->|"runtime hooks"| events
loader -->|"activates"| events
loader -->|"loads"| api
loader -->|"manages"| loadercfg
loader -->|"checks updates"| loadergh
events -->|"publishes via"| api
api -->|"defines"| pluginbase
api -->|"exposes"| corewrap
api -->|"supplies primitives"| coreinfra
events -->|"feeds"| customitems
events -->|"feeds"| customroles
api -->|"supports"| customitems
api -->|"supports"| customroles
permissions -->|"integrates with"| loader
credittags -->|"consumes"| events
example -->|"demonstrates"| api
example -->|"subscribes to"| events
installer -->|"installs"| loader
docs -->|"documents"| api
docs -->|"documents"| events
ci -->|"orchestrates"| packaging
packaging -->|"builds"| loader
packaging -->|"builds"| customitems

click loader "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Loader/Loader.cs"
click events "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Events/Events.cs"
click api "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.API/Exiled.API.csproj"
click pluginbase "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.API/Features/Plugin.cs"
click corewrap "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.API/Features/Player.cs"
click coreinfra "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.API/Features/Core/StateMachine/StateController.cs"
click customitems "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.CustomItems/CustomItems.cs"
click customroles "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.CustomRoles/CustomRoles.cs"
click permissions "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Permissions/Permissions.cs"
click credittags "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.CreditTags/CreditTags.cs"
click example "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Example/Example.cs"
click installer "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Installer/Program.cs"
click docs "https://github.com/exmod-team/exiled/blob/master/EXILED/docs/docfx.json"
click ci "https://github.com/exmod-team/exiled/blob/master/.github/workflows/main.yml"
click packaging "https://github.com/exmod-team/exiled/blob/master/EXILED/build.ps1"
click loadergh "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Loader/GHApi/ApiProvider.cs"
click loadercfg "https://github.com/exmod-team/exiled/blob/master/EXILED/Exiled.Loader/ConfigManager.cs"

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 loader,events,api,pluginbase,corewrap,coreinfra,loadergh,loadercfg toneBlue
class customitems,customroles,permissions,credittags toneAmber
class installer,docs,ci,packaging toneMint
class example toneRose
class game toneNeutral
```

## Components

### Runtime framework

Core assemblies that instrument the game and expose the plugin API.

- [Loader](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Loader/Loader.cs): bootstrap/runtime · Discovers EXILED assemblies, loads plugins, manages config, translations, and updates. · `EXILED/Exiled.Loader/Loader.cs`
- [Events](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Events/Events.cs): patch/event bridge · Harmony-style patches and handlers that translate game behavior into framework events. · `EXILED/Exiled.Events/Events.cs`
- [API](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.API/Exiled.API.csproj): public framework · Stable plugin-facing wrappers, enums, interfaces, and utility types. · `EXILED/Exiled.API/Exiled.API.csproj`
- [Plugin base](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.API/Features/Plugin.cs): plugin contract · Core plugin abstraction and shared contract types for authors. · `EXILED/Exiled.API/Features/Plugin.cs`
- [Wrappers](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.API/Features/Player.cs): entity wrappers · Live game abstractions for players, roles, items, doors, map, server, and round state. · `EXILED/Exiled.API/Features/Player.cs`
- [Core infra](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.API/Features/Core/StateMachine/StateController.cs): runtime primitives · State machines, dynamic events, pools, settings, and base behavior helpers. · `EXILED/Exiled.API/Features/Core/StateMachine/StateController.cs`
- [Update client](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Loader/GHApi/ApiProvider.cs): release client · GitHub release API client and updater models used by the loader. · `EXILED/Exiled.Loader/GHApi/ApiProvider.cs`
- [Config system](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Loader/ConfigManager.cs): loader support · Configuration, translation, YAML conversion, and plugin priority support. · `EXILED/Exiled.Loader/ConfigManager.cs`

### Feature modules

Optional assemblies built on top of the core runtime.

- [Custom items](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.CustomItems/CustomItems.cs): feature module · Framework for defining custom items, their events, and admin commands. · `EXILED/Exiled.CustomItems/CustomItems.cs`
- [Custom roles](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.CustomRoles/CustomRoles.cs): feature module · Framework for custom roles, abilities, parsers, and role commands. · `EXILED/Exiled.CustomRoles/CustomRoles.cs`
- [Permissions](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Permissions/Permissions.cs): admin module · Permission and group management commands, models, and YAML-backed data. · `EXILED/Exiled.Permissions/Permissions.cs`
- [Credit tags](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.CreditTags/CreditTags.cs): feature module · Tag/rank display subsystem with database-backed handlers and commands. · `EXILED/Exiled.CreditTags/CreditTags.cs`

### Tooling & docs

Installer, packaging, docs, and repository automation.

- [Installer](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Installer/Program.cs): setup utility · Standalone setup utility for operational installation tasks. · `EXILED/Exiled.Installer/Program.cs`
- [Docs](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/docs/docfx.json): documentation · DocFX documentation and getting-started guides for users and plugin authors. · `EXILED/docs/docfx.json`
- [GitHub Actions](https://github.com/exmod-team/exiled/blob/HEAD/.github/workflows/main.yml): automation · Build, docs, release, and publishing workflows. · `.github/workflows/main.yml`
- [Packaging](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/build.ps1): release tooling · Build and packaging scripts plus NuGet manifest definition. · `EXILED/build.ps1`

### Consumer example

Reference plugin showing downstream usage of the framework.

- [Example plugin](https://github.com/exmod-team/exiled/blob/HEAD/EXILED/Exiled.Example/Example.cs): reference consumer · Sample downstream plugin showing handlers, commands, and configuration usage. · `EXILED/Exiled.Example/Example.cs`

### Other components

- **SCP:SL server**: external game runtime · External game process and internal classes that EXILED hooks at runtime.

## Connections

- SCP:SL server → Events: runtime hooks · Patches intercept game methods and convert them into EXILED events.
- Loader → Events: activates · Loader brings the event bridge into the server process.
- Loader → API: loads · Loader initializes the framework assemblies and shared contracts.
- Loader → Config system: manages · Configuration, translations, and plugin loading behavior are coordinated here.
- Loader → Update client: checks updates · Loader can query releases and prepare version/update data.
- Events → API: publishes via · Event args and handlers are built on the public wrapper layer.
- API → Plugin base: defines · Plugin authors implement the core API contract.
- API → Wrappers: exposes · The API provides typed wrappers over in-game entities and systems.
- API → Core infra: supplies primitives · Common framework infrastructure is shared through the API layer.
- Events → Custom items: feeds · Custom item behavior is implemented on top of framework events.
- Events → Custom roles: feeds · Custom role lifecycle and ability execution depend on the event bridge.
- API → Custom items: supports · Custom items use the API abstractions and wrapper semantics.
- API → Custom roles: supports · Custom roles are built on shared plugin-facing types.
- Permissions → Loader: integrates with · Permission data and commands participate in runtime management.
- Credit tags → Events: consumes · Credit tag behavior reacts to framework events.
- Example plugin → API: demonstrates · The sample plugin shows intended API usage.
- Example plugin → Events: subscribes to · The sample plugin registers event handlers against the event system.
- Installer → Loader: installs · Installer prepares the runtime loader and supporting files.
- Docs → API: documents · Docs explain plugin structure and API usage.
- Docs → Events: documents · Docs cover event handling and plugin patterns.
- GitHub Actions → Packaging: orchestrates · Workflows coordinate builds, packaging, docs, and release publication.
- Packaging → Loader: builds · Scripts and manifests package the runtime assemblies.
- Packaging → Custom items: builds · Feature modules are packaged for distribution.
