# Lords of Ash — Mistborn: The Final Empire CK3 Mod

A Crusader Kings III total conversion mod set in Brandon Sanderson's Mistborn
universe during the Final Empire era. CK3 version 1.18.*.

## Project Structure

```
lords_of_ash/          # The mod itself (CK3 mod directory)
  common/                       # Game data definitions
    culture/                    # Cultures: noble_scadrian, skaa, terris
    decisions/                  # Player decisions (balls, snapping, breeding)
    dynasties/                  # 10 Great Houses
    dynasty_houses/
    landed_titles/              # Dominances and holdings
    men_at_arms_types/          # Hazekillers, Koloss, Mistborn Agents, etc.
    modifiers/                  # Character and province modifiers
    on_action/                  # Game hooks (birthday, yearly pulse, game start)
    religion/                   # Steel Ministry, Terris, Survivorism, Cult of Ruin
    scripted_effects/           # Reusable effect blocks
    scripted_triggers/          # Reusable condition checks
    traits/                     # Allomancy, Feruchemy, Hemalurgy traits
  events/                       # Event chains (snapping, balls, Lord Ruler, etc.)
  history/                      # Starting characters and title holders
  localization/english/         # All display strings (l_english.yml)
lords-of-ash.mod       # Outer mod descriptor (has path field)
docs/
  lore/                         # Mistborn universe reference material
  bookmarks/                    # Story arc planning (characters, scenarios)
  ck3-modding/                  # CK3 modding reference
```

## CK3 Modding Conventions

### File Naming
- Prefix data files with `00_` for load order: `00_allomancy_traits.txt`
- Event files use descriptive names: `snapping_events.txt`, `ball_events.txt`
- Localization files: `mistborn_<category>_l_english.yml`

### Trait Naming
Traits use the `trait_` prefix consistently:
- Misting traits: `trait_misting_<name>` (e.g., `trait_misting_coinshot`, `trait_misting_lurcher`)
- Mistborn: `trait_mistborn`
- Potential: `trait_allomantic_potential`
- Feruchemy: `trait_feruchemist`, `trait_feruchemical_potential`
- Hemalurgy: `trait_hemalurgist`, `trait_hemalurgic_spike_<type>`
- Strength: `trait_allomantic_strength_weak`, `_strong`, `_savant`

### Scripted Triggers/Effects Naming
- Triggers end with `_trigger`: `is_allomancer_trigger`, `is_mistborn_trigger`
- Effects end with `_effect`: `activate_allomancy_effect`

### Event Namespaces
- `mistborn_snapping` — Allomantic awakening events
- `mistborn_ball` — Noble ball social events
- `mistborn_lord_ruler` — Lord Ruler attention/interaction
- `mistborn_misc` — General events (kandra, misc)
- `mistborn_hemalurgy` — Hemalurgy events
- `mistborn_atium` — Atium economy events
- `mistborn_skaa` — Skaa population events
- `mistborn_skaa_allomancer` — Skaa Allomancer discovery/recruitment

### Localization
- All keys must be in `l_english` files with BOM encoding
- Key format: `<namespace>_<identifier>:<digit> "Display text"`
- Every trait, event, decision, title, and modifier needs a localization entry

## Core Mod Systems

### Allomancy
Genetic trait system. Characters carry `trait_allomantic_potential` (dormant)
until "snapped" through trauma, which activates a specific Misting type or
(rarely) full Mistborn. Inheritance chances are coded in trait definitions.

### Lord Ruler Attention
Variable-based tracking system (0–100). Actions that defy the Lord Ruler
increase attention; consequences escalate through tiers.

### Compounding
When a character has both an Allomantic and Feruchemical trait for the same
metal, compounding checks fire on the yearly pulse.

## Known Issues

See `lords_of_ash/REVIEW_NOTES.txt` for the full review. Key issues:
- Missing event files for several decisions (kandra, hemalurgy, atium, skaa)
- Missing modifier definitions (lord_ruler_attention tiers, ruin_influence, etc.)
- Missing traits for higher/Era 2 metals (chromium, aluminum, cadmium, bendalloy)
- Missing custom name lists for cultures

## Committing

Always use the `/commit` skill when committing changes. Never commit without
invoking it — it enforces conventional commit format, logical grouping, and
changelog maintenance.

## Skills

Always create skills in project scope (`.claude/skills/`) for this project, not
in user scope (`~/.claude/skills/`).

## Lore Reference

`docs/lore/mistborn-universe.md` — High-level setting, metallic arts, cosmic
forces, organizations, and themes. Consult this for lore accuracy when writing
events or designing new mechanics.