# joshuadevelopsgames/ironhold architecture

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

- Interactive diagram: https://gitdiagram.com/joshuadevelopsgames/ironhold
- Repository: https://github.com/joshuadevelopsgames/ironhold

## Overview

#### Purpose and runtime
Ironhold is a Java 21, Minecraft 26.1.2 NeoForge RPG-overhaul mod, loaded on both dedicated server and clients. Its primary mod entry points are `src/main/java/kingdom/smp/Ironhold.java` and `src/main/java/kingdom/smp/IronholdClient.java`; game registration is centralized through `ModItems`, `ModBlocks`, `ModEntities`, effects, sounds, particles, attachments, and worldgen registries.

#### Bootstrap, events, and client/server boundary
NeoForge lifecycle and gameplay events drive server-authoritative systems; client initialization installs renderers, screens, HUD, and input behavior. `src/main/java/kingdom/smp/IronholdGameEvents.java`, `src/main/java/kingdom/smp/ModAttachments.java`, and `src/main/java/kingdom/smp/client/ClientNeoForgeEvents.java` are key integration points. Mixins alter vanilla behavior where events/registries are insufficient, with declarations in `src/main/resources/ironhold.mixins.json` and implementations under `src/main/java/kingdom/smp/mixin`.

#### RPG progression and persistent player/world state
Classes, kingdoms, class XP, skills, and abilities form the core progression domain. `src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java`, `src/main/java/kingdom/smp/rpg/RpgProgression.java`, and `src/main/java/kingdom/smp/rpg/ability/AbilityDispatch.java` define player progression and execution. Profession progression is parallel in `src/main/java/kingdom/smp/skill/PlayerSkillState.java` and `src/main/java/kingdom/smp/skill/SkillEventHandlers.java`. World/server persistence uses SavedData-style components such as `src/main/java/kingdom/smp/world/KingdomWorldData.java`; client mirrors receive synchronized state rather than owning it.

#### Networking and interactive UI
`src/main/java/kingdom/smp/net/ModNetworking.java` is the explicit client/server protocol boundary. Payloads carry player input and UI actions—class choices, ability casts, minigame results, dialogue, and state synchronization—between client screens/HUD and server services. Examples include `src/main/java/kingdom/smp/net/AbilityCastPayload.java`, `src/main/java/kingdom/smp/net/SyncRpgDataPayload.java`, and `src/main/java/kingdom/smp/client/screen/KingsConsoleScreen.java`. Server validates and mutates authoritative state; clients render cached/synced views.

#### Content, combat, and game systems
Custom items, blocks, entities, effects, and event handlers implement the playable content layer. Registries expose them to Minecraft, while domain packages implement behavior: `src/main/java/kingdom/smp/entity/`, `src/main/java/kingdom/smp/item/`, and `src/main/java/kingdom/smp/block/`. Cross-cutting systems include gear quality/affixes (`src/main/java/kingdom/smp/gear/AffixRoller.java`), quests (`src/main/java/kingdom/smp/quest/QuestService.java`), and minigames (`src/main/java/kingdom/smp/fishing/FishingMinigameManager.java`, `src/main/java/kingdom/smp/blacksmithing/BlacksmithingMinigameManager.java`).

#### World simulation and generation
The mod adds dimensions, portals, moon gravity, seasons, biome content, and a substantial RTF terrain generator. Major boundaries are `src/main/java/kingdom/smp/moon/ModMoonDimensions.java`, `src/main/java/kingdom/smp/seasons/Seasons.java`, and `src/main/java/kingdom/smp/rtf/RTFBootstrap.java`. Runtime code combines with data-driven dimensions, biome modifiers, features, tags, and recipes under `src/main/resources/data/ironhold/`. A separate embedded `milkucha.trmt` erosion module has its own bootstrap at `src/main/java/milkucha/trmt/TRMT.java`.

#### AI NPC and voice integration
Voiced NPCs bridge in-game entities/dialogue to optional external AI services. `src/main/java/kingdom/smp/ai/NpcSpeech.java` coordinates conversation; `OpenRouterClient`, `ElevenLabsClient`, and `OpenAiWhisperClient` call LLM, text-to-speech, and speech-to-text services. Voice capture integrates the bundled Simple Voice Chat dependency via `src/main/java/kingdom/smp/ai/svc/IronholdVoicechatPlugin.java`. Keys remain server-side in world-specific configuration (`src/main/java/kingdom/smp/Config.java`); absent credentials disable this subsystem without blocking gameplay.

#### Delivery and adjacent modules
Gradle builds the primary mod from `build.gradle`; `scripts/deploy-mod.sh` packages and uploads the jar to a remote Minecraft deployment. The repository also contains independently buildable/packaged adjuncts: a mirror-rendering NeoForge mod under `mirrors mod/src/main/java/kingdom/smp/mirrors/`, an admin datapack under `admin_datapack/`, and a shaderpack under `shaderpack/Lanthorn/`. They are operational companions, not core Ironhold runtime packages.

Main entry points: [`src/main/java/kingdom/smp/Ironhold.java`](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/Ironhold.java) (Ironhold server entry), [`src/main/java/kingdom/smp/net/ModNetworking.java`](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/net/ModNetworking.java) (Mod networking), [`src/main/java/kingdom/smp/IronholdGameEvents.java`](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/IronholdGameEvents.java) (Gameplay events), [`src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java`](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java) (RPG progression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Mod Runtime"]
  node_server_entry["Ironhold server entry<br/>NeoForge entrypoint<br/>[Ironhold.java]"]
  node_registries["Content registries<br/>game registration"]
  node_game_events["Gameplay events<br/>event integration"]
  node_attachments["State attachments<br/>persistent attachment"]
  node_mixins["Vanilla mixins<br/>behavior patching"]
end

subgraph group_progression["Authoritative RPG"]
  node_rpg_state[("RPG progression<br/>player domain state")]
  node_ability_dispatch["Ability execution<br/>combat service"]
  node_skill_state["Profession skills<br/>player domain state"]
  node_world_data[("World persistent state<br/>SavedData")]
  node_content_systems["Content &amp; game systems<br/>[QuestService.java]"]
end

subgraph group_client["Client &amp; Protocol"]
  node_networking["Mod networking<br/>client-server protocol<br/>[ModNetworking.java]"]
  node_client_entry["Ironhold client entry<br/>NeoForge client entrypoint"]
  node_client_events["Client event integration<br/>render input integration"]
  node_screens_hud["Screens &amp; HUD<br/>client UI"]
end

subgraph group_world["World Systems"]
  node_world_simulation["Dimensions &amp; seasons<br/>world simulation"]
  node_terrain_generator["RTF terrain generator<br/>worldgen bootstrap<br/>[RTFBootstrap.java]"]
  node_world_data_assets["Worldgen data assets<br/>data-driven content"]
  node_trmt["TRMT erosion module<br/>embedded terrain module<br/>[TRMT.java]"]
end

subgraph group_ai["Optional AI Voice"]
  node_npc_speech["NPC speech coordinator<br/>AI dialogue service<br/>[NpcSpeech.java]"]
  node_voicechat["Voice chat bridge<br/>voice capture plugin"]
end

subgraph group_adjuncts["Delivery &amp; Companions"]
  node_build_deploy["Build &amp; deployment<br/>Gradle packaging<br/>[build.gradle]"]
  node_companions["Companion modules<br/>adjunct packages"]
end

node_server_entry -->|"registers"| node_registries
node_server_entry -->|"subscribes"| node_game_events
node_server_entry -->|"installs"| node_attachments
node_server_entry -.->|"loads with mod"| node_mixins
node_game_events -->|"updates"| node_rpg_state
node_game_events -->|"updates"| node_skill_state
node_game_events -->|"drives"| node_content_systems
node_attachments -->|"persists player state"| node_rpg_state
node_rpg_state -->|"authorizes casts"| node_ability_dispatch
node_ability_dispatch -->|"applies gameplay effects"| node_content_systems
node_world_data -->|"persists world state"| node_world_simulation
node_registries -->|"exposes content"| node_content_systems
node_registries -->|"registers world content"| node_world_simulation
node_world_data_assets -->|"defines content"| node_world_simulation
node_terrain_generator -->|"generates terrain for"| node_world_simulation
node_trmt -->|"provides erosion"| node_terrain_generator
node_client_entry -->|"initializes"| node_client_events
node_client_events -->|"installs UI and input"| node_screens_hud
node_screens_hud -->|"sends actions"| node_networking
node_networking -->|"syncs and validates"| node_rpg_state
node_networking -->|"forwards casts"| node_ability_dispatch
node_networking -->|"forwards UI results"| node_content_systems
node_npc_speech -->|"receives voice capture"| node_voicechat
node_npc_speech -->|"synchronizes dialogue"| node_networking
node_build_deploy -->|"packages mod"| node_server_entry
node_companions -.->|"operationally adjacent"| node_build_deploy

click node_server_entry "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/Ironhold.java"
click node_game_events "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/IronholdGameEvents.java"
click node_attachments "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ModAttachments.java"
click node_mixins "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/resources/ironhold.mixins.json"
click node_rpg_state "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java"
click node_ability_dispatch "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rpg/ability/AbilityDispatch.java"
click node_skill_state "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/skill/PlayerSkillState.java"
click node_world_data "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/world/KingdomWorldData.java"
click node_content_systems "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/quest/QuestService.java"
click node_networking "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/net/ModNetworking.java"
click node_client_entry "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/IronholdClient.java"
click node_client_events "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/client/ClientNeoForgeEvents.java"
click node_screens_hud "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/client/screen/KingsConsoleScreen.java"
click node_world_simulation "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/moon/ModMoonDimensions.java"
click node_terrain_generator "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rtf/RTFBootstrap.java"
click node_trmt "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/milkucha/trmt/TRMT.java"
click node_npc_speech "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ai/NpcSpeech.java"
click node_voicechat "https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ai/svc/IronholdVoicechatPlugin.java"
click node_build_deploy "https://github.com/joshuadevelopsgames/ironhold/blob/main/build.gradle"

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_entry,node_registries,node_game_events,node_attachments,node_mixins toneBlue
class node_rpg_state,node_ability_dispatch,node_skill_state,node_world_data,node_content_systems toneAmber
class node_networking,node_client_entry,node_client_events,node_screens_hud toneMint
class node_world_simulation,node_terrain_generator,node_world_data_assets,node_trmt toneRose
class node_npc_speech,node_voicechat toneIndigo
class node_build_deploy,node_companions toneTeal
```

## Components

### Mod Runtime

- [Ironhold server entry](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/Ironhold.java): NeoForge entrypoint · `src/main/java/kingdom/smp/Ironhold.java`
- **Content registries**: game registration · Registers items, blocks, entities, effects, sounds, particles, attachments, and worldgen.
- [Gameplay events](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/IronholdGameEvents.java): event integration · `src/main/java/kingdom/smp/IronholdGameEvents.java`
- [State attachments](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ModAttachments.java): persistent attachment · `src/main/java/kingdom/smp/ModAttachments.java`
- [Vanilla mixins](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/resources/ironhold.mixins.json): behavior patching · `src/main/resources/ironhold.mixins.json`

### Authoritative RPG

- [RPG progression](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java): player domain state · Classes, kingdoms, XP, skills, and abilities are server-authoritative. · `src/main/java/kingdom/smp/rpg/PlayerKingdomRpgData.java`
- [Ability execution](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rpg/ability/AbilityDispatch.java): combat service · `src/main/java/kingdom/smp/rpg/ability/AbilityDispatch.java`
- [Profession skills](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/skill/PlayerSkillState.java): player domain state · `src/main/java/kingdom/smp/skill/PlayerSkillState.java`
- [World persistent state](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/world/KingdomWorldData.java): SavedData · `src/main/java/kingdom/smp/world/KingdomWorldData.java`
- [Content & game systems](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/quest/QuestService.java): items entities quests gear minigames · Implements playable content, affixes, quests, fishing, and blacksmithing. · `src/main/java/kingdom/smp/quest/QuestService.java`

### Client & Protocol

- [Mod networking](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/net/ModNetworking.java): client-server protocol · Carries validated actions and synchronized state. · `src/main/java/kingdom/smp/net/ModNetworking.java`
- [Ironhold client entry](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/IronholdClient.java): NeoForge client entrypoint · `src/main/java/kingdom/smp/IronholdClient.java`
- [Client event integration](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/client/ClientNeoForgeEvents.java): render input integration · `src/main/java/kingdom/smp/client/ClientNeoForgeEvents.java`
- [Screens & HUD](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/client/screen/KingsConsoleScreen.java): client UI · Renders cached synchronized state and sends player actions. · `src/main/java/kingdom/smp/client/screen/KingsConsoleScreen.java`

### World Systems

- [Dimensions & seasons](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/moon/ModMoonDimensions.java): world simulation · Provides moon dimension, portals, gravity, and seasonal behavior. · `src/main/java/kingdom/smp/moon/ModMoonDimensions.java`
- [RTF terrain generator](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/rtf/RTFBootstrap.java): worldgen bootstrap · `src/main/java/kingdom/smp/rtf/RTFBootstrap.java`
- **Worldgen data assets**: data-driven content · Dimensions, biome modifiers, features, tags, and recipes.
- [TRMT erosion module](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/milkucha/trmt/TRMT.java): embedded terrain module · `src/main/java/milkucha/trmt/TRMT.java`

### Optional AI Voice

- [NPC speech coordinator](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ai/NpcSpeech.java): AI dialogue service · Optional server-side bridge for conversation and voice. · `src/main/java/kingdom/smp/ai/NpcSpeech.java`
- [Voice chat bridge](https://github.com/joshuadevelopsgames/ironhold/blob/main/src/main/java/kingdom/smp/ai/svc/IronholdVoicechatPlugin.java): voice capture plugin · `src/main/java/kingdom/smp/ai/svc/IronholdVoicechatPlugin.java`

### Delivery & Companions

- [Build & deployment](https://github.com/joshuadevelopsgames/ironhold/blob/main/build.gradle): Gradle packaging · `build.gradle`
- **Companion modules**: adjunct packages · Mirror mod, admin datapack, and shaderpack ship independently.

## Connections

- Ironhold server entry → Content registries: registers
- Ironhold server entry → Gameplay events: subscribes
- Ironhold server entry → State attachments: installs
- Ironhold server entry → Vanilla mixins: loads with mod
- Gameplay events → RPG progression: updates
- Gameplay events → Profession skills: updates
- Gameplay events → Content & game systems: drives
- State attachments → RPG progression: persists player state
- RPG progression → Ability execution: authorizes casts
- Ability execution → Content & game systems: applies gameplay effects
- World persistent state → Dimensions & seasons: persists world state
- Content registries → Content & game systems: exposes content
- Content registries → Dimensions & seasons: registers world content
- Worldgen data assets → Dimensions & seasons: defines content
- RTF terrain generator → Dimensions & seasons: generates terrain for
- TRMT erosion module → RTF terrain generator: provides erosion
- Ironhold client entry → Client event integration: initializes
- Client event integration → Screens & HUD: installs UI and input
- Screens & HUD → Mod networking: sends actions
- Mod networking → RPG progression: syncs and validates
- Mod networking → Ability execution: forwards casts
- Mod networking → Content & game systems: forwards UI results
- NPC speech coordinator → Voice chat bridge: receives voice capture
- NPC speech coordinator → Mod networking: synchronizes dialogue
- Build & deployment → Ironhold server entry: packages mod
- Companion modules → Build & deployment: operationally adjacent