# PKCore - Caching & Performance Guide

PKCore includes a sophisticated caching and optimization system designed to handle large texture packs (like Project Kyaro) without compromising game startup times or runtime performance.

---

## 1. Texture Manifest Caching

Scanning thousands of custom PNG and DDS files every time the game starts can significantly delay the "Press Start" screen. PKCore solves this with the **Texture Manifest Cache**.

### How it works
- **First Run**: PKCore performs a deep scan of your `PKCore/Textures/` and `PKCore/00-Mods/` folders and builds a complete index of every replaceable texture. This index is saved to `PKCore/Cache/texture_manifest.xml`.
- **Subsequent Runs**: PKCore simply loads the XML file. This reduces startup indexing time from several seconds down to ~20ms.
- **Config Hash Validation**: The manifest includes a "Config Hash" (v3.0) that tracks 10 configuration settings affecting texture selection: `SavePointColor`, `LoadLauncherUITextures`, `EnableProjectKyaroSprites`, `MinimalUI`, `ForceControllerPrompts`, `ControllerPromptType`, `MercFortFence`, `ClassicSaveWindow`, and `TirRunTexture`. If you change any of these settings, the hash changes, automatically invalidating the cache and triggering a rebuild.

### Texture Directory Filtering
PKCore includes intelligent texture filtering that allows you to selectively disable specific texture categories for debugging or preference:
- **Launcher UI Textures** (`LoadLauncherUITextures = false`): Skips textures in `Launcher-Mod` or `/launcher/` folders.
- **Project Kyaro Sprites** (`EnableProjectKyaroSprites = false`): Skips textures in `\PKS1\` and `\PKS2\` folders. 
- **Minimal UI Textures** (`MinimalUI = false`): Skips textures containing "minimal" in their path.

### Manual Cache Control
- **Disable Caching**: Set `EnableTextureManifestCache = false` to force fresh scans every startup (useful for texture development).
- **Force Rebuild**: Delete the `PKCore/Cache/` folder or change any tracked config setting.
- **Cache Location**: `PKCore/Cache/texture_manifest.xml`

---

## 2. Load Order & Priority System

When multiple textures share the same name, PKCore uses a strict **3-Layer Priority System** to determine which file wins. This allows mods to override base textures without deleting them.

| Priority | Layer | Folder Location | Description |
| :--- | :--- | :--- | :--- |
| **1 (Low)** | **Base** | Root of `Textures/` | Basic textures and individual replacements. |
| **2 (Mid)** | **Game Specific** | `Textures/GSD1/`, `Textures/GSD2/` | Game-specific overrides. Only loaded when playing that specific game. |
| **3 (High)** | **Mods** | `PKCore/00-Mods/<ModName>/` | **High Priority Overrides.** Files here ALWAYS win. Multiple mods sorted alphabetically (`zz_` prefix wins). |

**Rule of Thumb:** If you want to force a texture or sound to load with highest priority, put it in `PKCore/00-Mods/`.

---

## 3. High-Performance DDS Loading

For the absolute best performance, PKCore supports pre-compressed **DDS** files across textures, sprites, UI masks, and dialogue portraits.

- **Fastest Loading**: DDS files are already in the GPU's native format. They skip expensive runtime processing entirely.
- **In-Place Replacement**: PKCore performs "Low-Level In-Place Replacement" for DDS files, copying raw pixel data directly into the game's original texture memory. This preserves all game references while swapping the visual content.
- **Priority**: `.dds` files take priority over `.png`/`.jpg`/`.tga` if multiple valid files exist in the same priority layer.
- **Formats Supported**: BC1 (DXT1) for opaque textures, BC3 (DXT5) for textures with transparency, BC7 (with DX10 header support) for high-quality compression.
- **Other Formats**: PKCore also supports `.png`, `.jpg`, `.jpeg`, and `.tga` image files.

---

## 4. Intelligent Scene-Based Memory Caching

PKCore features a "Smart Memory" management system that tracks custom textures at runtime and optimizes VRAM usage based on your current location.

### How it works
- **Scene Tracking**: PKCore monitors which textures are loaded in specific game areas (e.g., world map vs. town).
- **Automatic Cleanup**: When you move between major game scenes (e.g., entering a town from the world map), PKCore identifies textures that are no longer relevant and **purges** them from memory.
- **Persistence System**: Essential textures and preloaded game atlases are marked as **Persistent** (`DontDestroyOnLoad`) and are NEVER purged, ensuring UI stability and smooth transitions.
  
**Persistent Patterns & Preloaded Atlases (Safe from Purge):**
- `window_` (UI Borders)
- `t_obj_savePoint` / `t_obj_savePoint_ball` (Save Points)
- `menu` (Menu Elements)
- `ui` (General UI)
- `dialog` (Dialog Boxes)
- `sactx` (Field & Battle Texture Atlases preloaded via `CustomTexturePersist`, e.g. `shu_battle_00_atlas`, `shu_field_01_atlas`, `shu_04_hd_atlas`)
- `fp_129` (Base portrait sprite template for NPC portrait system)
- Save Slot Mini Portraits (Cached in-memory via `SaveSlotPartyPortraitPatch`)

### Config Options
- `EnableMemoryCaching = true`: Activates the scene-based purge system (Recommended).
- `DetailedLogs = true`: Logs texture operations, memory stats, and purge events to the console.

---

## 5. In-Memory Save Slot Portrait Caching

PKCore features dedicated in-memory sprite and texture caching for **Save Slot Party Member Portraits** (`ShowSaveSlotPartyPortraits`):
- Dynamic lookup caching by character ID and Face ID (`$"{game}_{charId}"`).
- Instantaneous 0ms retrieval after initial load during save/load menu scrolling.
- Prioritizes custom DDS and PNG portraits from `PKCore/Textures/` over vanilla assets.

---

## 6. Performance Recommendations

| Scenario | Recommendation |
| :--- | :--- |
| **Normal Use** | Keep `EnableTextureManifestCache = false` (or `true` if your mod list is finalized) and `EnableMemoryCaching = true`. |
| **Texture Development** | Set `EnableTextureManifestCache = false` to force fresh scans when adding/removing files. |
| **Selective Modding** | Use `EnableProjectKyaroSprites = false` if you only want UI mods and not sprite replacements. |
| **Low VRAM Systems** | Ensure `EnableMemoryCaching = true` to prevent out-of-memory issues. |
| **Large Mod Packs** | Convert textures and portraits to **DDS** format (BC7 / BC3 / BC1) to eliminate load-time processing and stutter. |

---

## 7. Directory Layout Reference

```
PKCore/
├── Cache/
│   └── texture_manifest.xml      # Auto-generated texture index cache
├── Config/                       # Data-driven JSON configuration
│   ├── S2WarAbilities.json
│   ├── PortraitMappings.json
│   ├── PortraitVariants.json
│   ├── DialogOverrides.json
│   ├── S1SpeakerOverrides.json
│   └── S2SpeakerOverrides.json
├── Textures/
│   ├── *.png, *.dds, *.tga       # Base game textures (lowest priority)
│   ├── GSD1/                     # Suikoden 1 specific textures
│   │   ├── Portraits/            # S1 custom portraits (PNG / DDS)
│   │   └── NPCPortraits/         # S1 custom NPC portraits (PNG / DDS)
│   ├── GSD2/                     # Suikoden 2 specific textures
│   │   ├── Portraits/            # S2 custom portraits (PNG / DDS)
│   │   └── NPCPortraits/         # S2 custom NPC portraits (PNG / DDS)
│   ├── Portraits/                # Shared fallback portraits
│   ├── NPCPortraits/             # Shared fallback NPC portraits
│   └── SavePoint/                # Save point orb/crystal color variants
├── Sound/                        # Base CriWare ACB/AWB audio replacements
└── 00-Mods/                      # HIGHEST PRIORITY Mod Packages
    ├── PKS1/, PKS2/              # Project Kyaro sprites
    ├── Better-Launcher-BGM-Mod/  # Launcher BGM replacement
    └── CustomMod/                # User mod packages
```

***
*Note: NPC portrait injection is fully supported for both Suikoden I (`GSD1`) and Suikoden II (`GSD2`).*
*Note: The Texture Manifest Cache is located in `PKCore/Cache/`. To reset all caches, delete the `Cache/` folder and restart the game.*