Modules & libraries
Everything in the server is either a module (one game system, toggleable
at runtime) or a library (shared code under libs/, never toggleable,
never depending on a module). The split and the rules behind it are on the
Architecture page.
Each page below mirrors the component's README.md in the
mcrpg repository, adapted for this site.
The README is the authoritative copy; if the two disagree, update this page.
Modules
Tier 0 of the module priority list.
All five exist and pass their toggle tests. The kernel is the four CRITICAL
modules plus the module manager, which lives in server/ rather than as a
module.
| # | Module | Class | Kernel | What it does | Depends on |
|---|---|---|---|---|---|
| 0.1 | module manager | CRITICAL | ✔ | Loads, enables and disables modules and remembers their state. Provides /module. Part of server/, not a module. | core-api |
| 0.2 | permissions | CRITICAL | ✔ | Roles (player, moderator, admin, hermes) and permission checks; /role | — |
| 0.3 | logging | CRITICAL | ✔ | Attaches the console, ClickHouse and Discord sinks to the event pipeline | — |
| 0.4 | player-data | CRITICAL | ✔ | Owns the players table; loads, caches and saves player records | — |
| 0.5 | admin-api | CRITICAL | ✔ | Read-only localhost HTTP API with bearer tokens, for Hermes, the Discord bot and the future panel | permissions, logging |
| 0.6 | welcome | STANDARD | Welcome title, MOTD and server icon. The reference module every later module copies. | — |
:::note Manifest vs. runtime dependencies
The manifest dependencies field lists other modules a module needs
enabled. Library dependencies (core-api, data, log, …) are Gradle
dependencies and don't appear in the manifest — every module uses core-api,
and most use several others.
:::
Libraries
In the order Tier 0 built them (each is needed by the next).
| # | Library | What it provides |
|---|---|---|
| 1 | core-api | The module contract: ShatterveilModule, ModuleManifest, ModuleContext, SecurityClass, ServiceRegistry, ModuleLog |
| 2 | commands | The command builder that forces a description, usage, examples and a permission on every command, and generates the command reference |
| 3 | permissions | Role, PermissionTable, PermissionService and the CommandCondition helpers |
| 4 | data | ClickHouse access: async queries and inserts, migrations, PlayerRecord |
| 5 | security | Input validation, per-player rate limits, the guarded client-data channel |
| 6 | log | The event pipeline: redaction, hash chain, console/ClickHouse/Discord sinks |
| 7 | text and palette | House-style Adventure text helpers and the Night-theme colours |
| 8 | testing | Test helpers, including the toggle test every module must pass |
Planned but not yet built: content (YAML content loading, see
Adding content), gui (chest menus) and display
(holograms, damage numbers, HUD). Each arrives with the first module that needs
it.
Reading a module page
Every module page has the same sections, matching the README format rule 3 requires:
- What it does
- Manifest — id, version, security class, kernel flag, dependencies
- Settings — environment variables, if any
- Commands — with permissions; the full text is on the Commands page
- Events — what it listens to and what it sends, where relevant
- Security — what input is trusted and how it's validated
- When disabled — what players and other systems see
- Tests — what the module's test suite covers