# thenicelander/ck3_blood_mage architecture

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

- Interactive diagram: https://gitdiagram.com/thenicelander/ck3_blood_mage
- Repository: https://github.com/thenicelander/ck3_blood_mage

## Overview

##### Main Components
- Mod Descriptor & Configuration: At the root, files like descriptor.mod, .gitignore, and a few build/config files define the mod package and integration rules.
- Common Mechanics (“common” directory): This is the heart of the mod, including subdirectories for:
- Buildings: New building types related to blood magic.
- Decisions and interactions: Files for decision-making (e.g., attuning lifeforce, converting cults) and character interactions.
- Deathreasons, modifiers, opinion modifiers, religions, and scripted components: These define how blood magic influences game rules and character behaviors.
- Event Handling (“events” directory): Contains various event scripts that trigger blood magic actions (e.g., lifedrain events, conversions, power enhancements).
- Localization (“localization” directory): Provides English text files that ensure the new mechanics and events are properly translated and integrated into the game interface.
- LLM Context: Although not as common in every CK3 mod, these files appear to serve as reference configurations or contextual data for character, dynasty, and trait mechanics.
- Documentation (“docs” directory and description files): Guides for mod usage, illustrations, and any additional technical details.

##### Relationships and Interactions
- The "common" directory acts as the engine: it exposes game mechanics (decisions, interactions, modifiers) and connects directly to the event triggers.
- The “events” directory responds to game conditions and interacts with the decisions in the “common” files – for example, when a player uses an ability like “Drain Traits”, an event from the events folder is fired.
- Visual representation in “gfx” and textual/communications provided by “localization” ensures that players understand and engage with the Blood Mage system.
- The LLM Context files provide a secondary layer of data definitions that might support advanced logic or statistical modeling behind character attributes, interactions, and trait inheritance.

##### Architectural Patterns and Design Principles
- Modularity: The clear separation into directories (common, events, gfx, localization, etc.) reflects a modular design where each part deals with a specific function of the mod.
- Separation of Concerns: The mechanics (e.g., blood magic progression, lifeforce resource) are defined in their own directories so that changes in one area (say, decisions) can be managed independently of visuals (gfx) or in-game events.
- Extensibility: The separation into multiple files within common subdirectories (buildings, decisions, traits, modifiers) indicates that additional mechanics can be added in future updates without overhauling the entire system.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Mod Metadata & Configuration"
        descriptor["descriptor.mod"]
        gitignore[".gitignore"]
        preCommit[".pre-commit-config.yaml"]
        changelog["CHANGELOG.md"]
        license["LICENSE"]
        readme["README.md (Root)"]
    end

    subgraph "Core Mechanics (Common)"
        buildings["Buildings"]
        interactions["Character Interactions"]
        decisions["Decisions"]
        decisionGroups["Decision Groups"]
        modifiers["Modifiers"]
        scriptedEffects["Scripted Effects"]
        scriptedModifiers["Scripted Modifiers"]
        religion["Religion"]
        traits["Traits"]
        deathreasons["Deathreasons"]
        opinionModifiers["Opinion Modifiers"]
        scriptValues["Script Values"]
        charTemplates["Character Templates"]
        nicknames["Nicknames"]
        onAction["On Action Triggers"]
    end

    subgraph "Event Handling"
        events["Events"]
    end

    subgraph "Visual Assets"
        interfaceGraphics["Interface Graphics"]
        portraits["Portraits"]
    end

    subgraph "Localization"
        localizationFiles["Localization Files"]
    end

    subgraph "LLM Context"
        llmContext["LLM Context Files"]
    end

    subgraph "Documentation"
        docs["Docs"]
        descMD["description.md"]
        descTXT["description.txt"]
    end

    subgraph "Player Interface"
        playerInterface["Player Interface"]
    end

    subgraph "External Dashboard (Optional)"
        dashboard["External Dashboard"]
    end

    %% Connections between modules
    descriptor --> buildings
    descriptor --> interactions
    descriptor --> decisions

    interactions -->|"triggers"| events
    decisions -->|"triggers"| events
    scriptedEffects -->|"modifies"| events
    scriptedModifiers -->|"modifies"| events
    modifiers --> events

    events -->|"updates"| playerInterface

    interfaceGraphics --> playerInterface
    portraits --> playerInterface
    localizationFiles --> playerInterface

    %% Optional connection for auxiliary visualization
    dashboard --- events

    %% Styles
    classDef config fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef event fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef visual fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef localization fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef llm fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef docs fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef interface fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef optional fill:#CCD1D1,stroke:#566573,stroke-width:2px;

    class descriptor,gitignore,preCommit,changelog,license,readme config;
    class buildings,interactions,decisions,decisionGroups,modifiers,scriptedEffects,scriptedModifiers,religion,traits,deathreasons,opinionModifiers,scriptValues,charTemplates,nicknames,onAction core;
    class events event;
    class interfaceGraphics,portraits visual;
    class localizationFiles localization;
    class llmContext llm;
    class docs,descMD,descTXT docs;
    class playerInterface interface;
    class dashboard optional;

    %% Click Events for Mod Metadata
    click descriptor "https://github.com/thenicelander/ck3_blood_mage/blob/main/descriptor.mod"
    click gitignore "https://github.com/thenicelander/ck3_blood_mage/blob/main/.gitignore"
    click preCommit "https://github.com/thenicelander/ck3_blood_mage/blob/main/.pre-commit-config.yaml"
    click changelog "https://github.com/thenicelander/ck3_blood_mage/blob/main/CHANGELOG.md"
    click license "https://github.com/thenicelander/ck3_blood_mage/tree/main/LICENSE"
    click readme "https://github.com/thenicelander/ck3_blood_mage/blob/main/README.md"

    %% Click Events for Core Mechanics - Common
    click buildings "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/buildings"
    click interactions "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/character_interactions"
    click decisions "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/decisions"
    click decisionGroups "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/decision_group_types"
    click modifiers "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/modifiers"
    click scriptedEffects "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/scripted_effects"
    click scriptedModifiers "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/scripted_modifiers"
    click religion "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/religion"
    click traits "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/traits"
    click deathreasons "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/deathreasons"
    click opinionModifiers "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/opinion_modifiers"
    click scriptValues "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/script_values"
    click charTemplates "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/scripted_character_templates"
    click nicknames "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/nicknames"
    click onAction "https://github.com/thenicelander/ck3_blood_mage/tree/main/common/on_action"

    %% Click Event for Event Handling
    click events "https://github.com/thenicelander/ck3_blood_mage/tree/main/events"

    %% Click Events for Visual Assets
    click interfaceGraphics "https://github.com/thenicelander/ck3_blood_mage/tree/main/gfx/interface"
    click portraits "https://github.com/thenicelander/ck3_blood_mage/tree/main/gfx/portraits"

    %% Click Event for Localization
    click localizationFiles "https://github.com/thenicelander/ck3_blood_mage/tree/main/localization"

    %% Click Event for LLM Context
    click llmContext "https://github.com/thenicelander/ck3_blood_mage/tree/main/llm_context"

    %% Click Events for Documentation
    click docs "https://github.com/thenicelander/ck3_blood_mage/tree/main/docs"
    click descMD "https://github.com/thenicelander/ck3_blood_mage/blob/main/description.md"
    click descTXT "https://github.com/thenicelander/ck3_blood_mage/blob/main/description.txt"
```
