xyz_image_replacer 1.5

---

---

---

━ WHAT IT DOES

• Replaces event pictures and character portraits across all installed CK2 mods with custom/AI-generated images
• Loads last via dependencies — overrides all original mods without modifying them
• Fixes the race portrait bug where xyz_comp_patcher renamed race traits in .txt files but not in .gfx portrait files
• Pool expansion: add more images than the original slot count and the build script automatically generates overflow portraits with new DDS strips, traits, and GFX — up to 100 per category
• Supports 18 mods for event pictures and 7 mods for portraits — skips any not installed
  

---

━ THE TOOLS

Tool 1 — Event Picture Replacer
Replaces the big images shown in event popups. The reference HTML is a full event browser — not just a file list.

• Step 1: Open tool_event_replacer/0_Event_Reference.html in your browser — shows all 3,503 event picture slots across 18 mods with dimensions, fill status, and cross-mod shared texture detection (81 textures shared across mods highlighted to avoid duplicate work)
• Lightbox: Click any entry to open a side-by-side view — left: event picture, right: scrollable panel with resolved English event descriptions and option names parsed from 8,502 events across 18 mods' localisation files. Green → arrows on options let you follow event chains to the next picture directly in the lightbox.
• Step 2: Drop images into tool_event_replacer/1_Source_Images/[ModName]/gfx/event_pictures/ — filename must match the original (e.g. Stats.png for Stats.dds). Any format: PNG, JPG, BMP, TGA, WEBP
• Step 3: Double-click 2_Process_Events.bat — auto-resizes and converts to correct format
  

Tool 2 — Portrait Replacer
Replaces character face portraits. Pool-based — no manual naming or frame assignment needed.

• Step 1: Open tool_portrait_replacer/0_Portrait_Reference.html in your browser — shows all categories, frame counts, and how many source images you have so far
• Step 2: Drop images into tool_portrait_replacer/1_Source_Images/[race]/[gender]/ — filenames don't matter, slots filled alphabetically. 1024×1024 face closeups recommended. Any format.
• Step 3: Double-click 2_Process_Portraits.bat — assembles DDS portrait strips with automatic circular alpha masking
  

Named NPC Portraits
DWR and LF named characters (Ariel, Bloodrayne, Mey, Brielle…) normally share generic portrait traits with random characters. Drop a named image and they get their own unique portrait.

• DWR named: Drop <charname>.png into tool_portrait_replacer/1_Source_Images/dwr/named/ — see _CHARACTERS.txt in that folder for the full list of 38 supported names + gender
• LF named: Drop <charname>.png into tool_portrait_replacer/1_Source_Images/lf/named/ — supports 14 LF NPCs: Mey, Lynness, Lenora, Ying_Li, Mwamba, Desmona, Asha, Charlotte (main) · Brielle, Joseph, Kalyian, Valri, Amora (Scarlet Sisters) · Meeshka
• Each named NPC gets a unique xir_<n>_pic trait with weight 1000001 — overrides DWR/LF's generic portrait assignment
  

Build the Mod

• Double-click 3_Build_Mod.bat in the xyz_image_replacer/ root folder (not inside a tool subfolder)
• Collects ALL processed event pictures and portrait strips into the mod
• Creates unique portrait traits for DWR named NPCs (38 chars) and LF named NPCs (14 chars)
• Auto-detects pool expansion and generates overflow DDS strips, traits, GFX, and scripted_effects
• Generates LF race trait fix GFX overrides automatically
• Original mod folders are NEVER modified
• Fully re-runnable — add more images, re-process, re-build (9-phase build script)
  

Partial replacement is fine: 5 images in a 200-slot category → only first 5 slots replaced, rest keep originals. Add more → re-run → next slots fill in.

---

━ POOL EXPANSION

When you have more images than original slots, the build script automatically creates overflow portraits — the originals stay untouched and your extra images become new portrait options CK2 randomly picks from.

Original slot counts (female):

• Cheri caucasian / asian / south_asian — 26 slots each
• Elf / Neko / Kitsune / Fairy / Orc female — 26 slots each
• Demon female — 20 slots · Angel female — 24 slots
• Halfdragon female (DWSE lizard form) — 26 slots NEW
• Drow female (HouseIrae) — 26 slots NEW
• African female — NEW (no originals, all images are custom)
  

Male categories — all NEW (no originals to replace):

• human/male_caucasian · male_asian · male_indian · male_african
• elf/male · neko/male · kitsune/male · fairy/male · orc/male · demon/male · angel/male
• When 0 male images: falls back to original mod behavior — no output generated
  

Maximum: 100 portraits per category. Overflow traits are hidden (xir_portrait27 through 100), assigned with higher weight than originals so CK2 naturally distributes across the full pool.

---

━ PORTRAIT CATEGORIES

• human/female — DWR generic female
• human/female_caucasian — Cheri caucasian included
• human/female_asian — Cheri east_asian included
• human/female_indian — Cheri south_asian included
• human/female_african — African includedNEW
• human/male_caucasian — Male caucasian 100 includedNEW
• human/male_asian — Male east_asian 100 includedNEW
• human/male_indian · human/male_africanNEW(empty — bring your own)
• elf/female — LF Elves 100 included · elf/male(empty)
• orc/female — LF Orcs 100 included · orc/male(empty)
• demon/female — LF Demons 100 included · demon/male100 includedNEW
• angel/female — LF Angels 100 included · angel/male(empty)
• drow/female — HouseIrae Drow 100 included · drow/male(empty)
• halfelf/female — HouseIrae Half-Elf 100 included · halfelf/male(empty)
• neko/female — LF Neko 100 included · neko/male(empty)
• kitsune/female — LF Kitsune 100 included · kitsune/male(empty)
• fairy/female — LF Fairies 100 included · fairy/male(empty)
• halfdragon/female — DWSE lizard/humanoid form 100 includedNEW · Note: dragon (full form, 14 slots) and halfdragon (humanoid lizard, 26 slots) are separate portrait systems — most characters appear in halfdragon form
• vampire/female · ghost/female · goblin/femaleNEW (DWR v2.00 trait) · dragon/female (full form) · elemental/female · child/female + male(empty — bring your own)
• dwr/named — DWR named characters (38 NPCs, matched by filename) 66 included
• lf/named — LF named characters (14 NPCs, matched by filename) 9 includedNEW
  

Note on DWR races: DWR has many race traits not covered by dedicated portrait strips — wolf_kin (werewolf), horse_kin, nymph_kin, rabbit_kin, undead, xyz_futa and other therianthropes all fall through to human/female (DWR remedy/dw_portrait generic pool). Named DWR characters use dwr/named. Only traits with dedicated DWR or LF portraitType blocks have their own category here.

━ EVENT PICTURE CATEGORIES

S = Sex · R = Rape · B = Bondage · T = Tentacle · M = Magic · W = Combat · C = Court · A = Body · F = Race/Fantasy · O = Other

---

━ REQUIREMENTS

• Python 3.6+ — download & install, make sure to tick "Add Python to PATH" during setup
• Pillow — after installing Python, open a command prompt and run: pip install Pillow
• texconv.exe — already included, no download needed
  

Dependency mods (must be enabled):

• xyz_comp_patcher · Cheri Portraits · Dark World Reborn · LuxuriaFantasia
• ElementalLove · Tale of Nine Tails · HouseIrae · AOH · WearAndTearNEW
  

---

━ INSTALLATION

1. Place xyz_image_replacer/ folder in your CK2 mod directory
2. Place xyz_image_replacer.mod in your CK2 mod directory
3. Enable xyz_image_replacer in the CK2 launcher (all dependency mods must also be enabled)
   

CK2 mod folder: Documents/Paradox Interactive/Crusader Kings II/mod/ (Windows)

---

━ SUPPORTED MODS

Event Pictures (18 mods):
IST · bdsmSociety · LuxuriaFantasia · Dark World Reborn · Cheri Tentacle Dreams · LF Extras · ABM · Demonkingdom · HouseIrae · ElementalLove · Tale of Nine Tails · Tentacled Dreams Extended · LF Beyond Heresy · Crusader Milk · AOH · ACM · xyz_comp_patcher · WearAndTear
Tested against: DWR v2.01 · Cheri Tentacle Dreams v4.6 (final CK2 release) · xyz_comp_patcher v2.1i · LF Extras v1.0.4

Portraits (7 mods):
Cheri Portraits · Dark World Reborn · LuxuriaFantasia · ElementalLove · Tale of Nine Tails · HouseIrae · AOH

Any mod not installed is silently skipped — no errors.

---

━ VERSION HISTORY

• v1.5 — LF Named NPC Portraits + DWR Gender Tracking. 14 LF named NPCs get unique xir_lf_<n>_pic traits (weight 1000001 > LF's 100000): Mey, Lynness, Lenora, Ying_Li, Mwamba, Desmona, Asha, Charlotte (main); Brielle, Joseph, Kalyian, Valri, Amora (Scarlet Sisters); Meeshka. New seeding event (xir_lf_named.1, on_startup) adds xir_ trait to chars with original lf_npc_* traits — no scripted_effect override needed. New source folder: lf/named/<charname>.png. DWR _CHARACTERS.txt now includes gender column. Phase [4/9] now handles both DWR + LF named NPCs.
• v1.4 — DWR Named NPC Portrait Support. 38 DWR named characters originally sharing generic portrait## traits get unique xir_<n>_pic traits, DDS strips, and portraitType entries (weight 1000001 > DWR's 1000000). Phase [4/9] parses dw_npc_scripted_effects.txt and overrides the scripted_effects with the new traits. Build script renumbered from 8 to 9 phases.
• v1.3h — Delayed Race Portrait Seeding for New Games. Fixed: drow/race portraits not assigned on new games — HouseIrae.13 converts characters to drow on day 1, ACM seeds AI drow on day 2-6, but the on_startup seeding fires at day 0 before these characters exist. New delayed re-seed event (xir_race_portraits.2) fires 30 days after game start, covers all 10 races with remove+add pattern (safe for already-seeded characters).
• v1.3g — DWSE Gender Gate + Drow Seeding Migration + Trait Dedup. Fixed: male halfdragon/lizard characters showed female portraits — DWSE strip has female (frames 1-21) and male (frames 22-26) in one DDS, our 100 female images filled all frames including male ones. Phase 4 now injects portrait_is_female = yes into the DWSE weight block. Fixed: drow/dragon/lizard portraits not assigned on existing saves where the v1 seeding flag already fired. New v2 migration block seeds only drow/dragon/lizard on existing saves. New v3 migration block for saves where v2 fired but effects weren't deployed yet (clean remove+add re-seed). Fixed: demon overflow traits duplicated — generate_lf_expansion_traits() generated per-category without dedup. Now groups by (trait_prefix, orig_slots). Total traits: 674 (down from 774), 0 duplicates.
• v1.3f — Race Portrait Seeding + Overflow for Drow, Dragon, Halfdragon. Fixed: HouseIrae drow and DWSE dragon/lizard characters showed human portraits at game start. Seeding event now covers 10 races (was 7): 7 LF races + drow + dragon + halfdragon/lizard. NEW: Pool expansion for Halfdragon (dwse_lizard, 26 slots) and Drow (HouseIrae, 26 slots) — both support up to 100 portraits with overflow DDS/traits/GFX/scripted_effects. NEW: halfdragon/female source category in tool_portrait_replacer (was previously miscategorized as human/female).
• v1.3e — WearAndTear Integration. WearAndTear added to DEPENDENCIES (load order) and NARRATIVE_MODS (472×472 standardization, 9 mods total). Category keywords expanded: "battle" += kill/murder/assassin/death/strike · "court" += rob/treasury/theft/steal/cuckold/depart/arrive/escape/captured.
• v1.3d — Narrative Event Size Standardization. Fixed: event pictures from non-IST mods were converted at original dimensions instead of 472×472 narrative standard. New NARRATIVE_MODS list ensures all narrative-heavy mod event pictures are standardized to 472×472. New --force flag for 2_Process_Events.bat — always re-converts all images (fixes Windows timestamp preservation issue where replaced source images were skipped).
• v1.3c — Event Context in Lightbox + README Stats. Lightbox now shows event context alongside the image (side-by-side): left side event picture, right side scrollable panel with event descriptions and option names. Localisation scanner reads 40,333 English text keys from 18 mods' CSV files. Token-based event parser extracts full structure of 8,502 events. Chain navigation: green → arrows on options jump directly to the next event's picture. EVENT_DATA JSON embedded in HTML (~5.5 MB, 3,503 sprite keys). Auto-generated replacement stats in README updated by Phase 8 of 3_Build_Mod.bat.
• v1.3b — Event Reference Shared Texture Detection. Cross-mod shared texture analysis: detects 81 textures used across 2+ mods. "Actionable" dashboard counter (3,165 unique). Green badge on primary entries, blue badge + greyed-out rows on duplicates. "Hide Shared" filter button.
• v1.3a — Event Reference Thumbnail Fix. Fixed wrong thumbnail path ("thumbnails/" instead of "_thumbnails/") — all ~3,400 preview images showed as broken icons.
• v1.3 — Instant Race Portraits + Bugfixes. Race portrait seeding on game startup (on_startup + on_chronicle_start, guarded by xir_race_portrait_seeding_done). Fixed: Neko/Kitsune gender gate skipped due to per-block portrait_is_female in GFX children. Fixed: overflow trait names used wrong prefix (lf_*_portrait instead of xir_*_portrait) — most visible for Demons (80% of assignments failed).
• v1.2 — LF Race Gender Gate Fix. Original LF adult race GFX files had no portrait_is_female gate — male race characters showed female race portraits. Build script now injects portrait_is_female = yes into all 5 adult race GFX overrides. Fixed Angel/Demon detection (bare pattern, no lf_ prefix).
• v1.1b — Save Migration + NOR Block Fix. One-time migration in CheriPortraits.10 clears all flags and reassigns portraits on first load. Fixed duplicate trait entries in caucasian portraitType NOR guard.
• v1.1a — random_list Wrapper Fix. Fixed missing random_list = { } wrapper in CheriPortraits.0 — without it CK2 ignored all portrait trait assignments.
• v1.1 — Male Portrait Support. 4 male Cheri ethnicity categories + 7 male LF race categories. Gender-split events and scripted effects. Up to 100 portraits per male category.
• v1.0b — African Ethnicity. New Cheri african pool (east/central/west African cultures). Falls back to south_asian when 0 images provided.
• v1.0a — Per-Ethnicity Random List Fix. Each ethnicity's random_list now only includes overflow traits with matching GFX frames.
• v1.0 — Initial release. Event picture replacement (18 mods), portrait replacement (7 mods), LF race trait fix, Cheri + LF race pool expansion up to 100 per category.