# Olympus Coliseum Mod Integration

KH3AP can turn the 25 cup clears from Olympus Coliseum 1.4.2/1.4.2.1 into Archipelago
locations without editing the original mod pak's contents. This integration
accepts these source pak SHA-256 values, then validates the reward tables before
installing a generated companion:

```text
9CFB5F5A9A12896690512FC7DAB073938A8E0E2828561A4EC72CE764DAED73E0
A32E44BA76FFB6E085AB93ED972694C0B93889313F2AD23A2313133D55001EC9
```

The first hash is the locally verified 1.4.2 reference. The second was reported
by a player using the newer release and was previously rejected by the outdated
single-hash gate. Its bytes have not been inspected locally; generation still
requires 23 reward tables with one row and 19 reward arrays each, plus packed
output readback. Unknown hashes remain rejected by both the client and CLI.

## Files and load order

### Third Party Mods tab

Olympus Coliseum is the default catalog entry. To add another mod, click **Add Mod**
to open the form. Enter its name, exact `.pak` filename, and optional download URL,
then click **Add Mod** in the dialog. **Cancel** closes the form without saving.
Custom entries are saved per installation in `Content/Archipelago Disabled Mods/third-party-mods.json`.
Use **Storage** to open the new entry's folder, extract the named pak there,
then click **Restore all**. Already installed paks with that filename are detected.
Custom mods use the same reversible **Remove all** / **Restore all** controls;
adding an entry does not download or enable it automatically.

The client lists Olympus Coliseum by Aproydtix with a Nexus download link and
the website version (1.4.2.1). This is catalog metadata, not an installed-version
detector: randomized AP cup rewards require an accepted source hash and successful
reward-table validation.

Use **Open Storage**, extract `zzzColiseumMod.pak` directly into that folder,
and stage each required boss mod in its own **Open Storage** folder:

- [Zodiac Phantom Aqua](https://www.nexusmods.com/kingdomhearts3/mods/2067?tab=files):
  main **Phantom Aqua** file, `PhantomAqua_BossBattle.pak`.
- [Key of Destiny - Data Roxas Boss](https://www.nexusmods.com/kingdomhearts3/mods/2150?tab=files):
  **Roxas Boss - Coliseum Version**, `RoxasBoss_ColiseumVersion.pak`.

The required files appear as child rows with their own download links and status.
Click **Restore all** to move the group into the configured mods directory
using the supported priority filename. **Remove all** moves it back without deleting
it. Existing priority-named installations are detected automatically. Both actions
require KH3 to be closed, preserve the mod bytes, and move any AP reward companion
with the full mod. The existing seed logic still controls the companion's reward
mode. Conflicting or duplicate full-mod copies block the action instead of being
overwritten. Both required boss paks move with Coliseum. Restore all also fills in
staged dependencies for an already-active Coliseum installation. Missing required
files block restoration before any files move; a failed move rolls the group back.
Remove all remains available for incomplete active groups. Other mods are left alone.
The Data Battle and legacy Roxas variants are not accepted as the Coliseum dependency;
active known alternate variants block restoration and are left for the user to move.

Filename protection follows the installed reference: the full mod must use
`zzzy_ColiseumMod_998_P.pak`, and the reward companion must use
`zzzz_APOlympusColiseumCompat_999_P.pak`. Restore normalizes recognized missing
or incorrect priority suffixes. Existing installations are normalized automatically
when the tab refreshes and before companion preparation, including without the GUI.
The group actions are **Remove all** / **Restore all**. Automatic renaming waits for
KH3 to close, preserves disabled companion suffixes and bytes, and refuses
duplicate destinations. It does not change the full mod to `999_P`: the companion
must retain the higher priority. Unknown paks and backup files are left alone.

For the standard install layout, storage is
`Content/Archipelago Disabled Mods/olympus-coliseum`, outside `Content/Paks` so
Unreal cannot discover inactive paks. It is scoped to the configured installation.
Tests simulate the Restore / Remove / Restore button sequence using fixture paks;
they do not validate the downloaded mod in gameplay.

Install the verified source pak once as `zzzy_ColiseumMod_998_P.pak`. Its bytes
remain unchanged; only the installed filename differs. The late `_998_P`
priority makes the Coliseum version of Apex win over Steam's official
`*_0_P.pak` updates so the entrance actors appear.

KH3AP builds `zzzz_APOlympusColiseumCompat_999_P.pak` above the full mod's
`_998_P` priority. The companion always overrides
`Content/Load/Tres/TresTreasureDataHE` and replaces every chest reward with
`ETresVictoryBonusKind::NONE`. This includes the mod's extra Olympus chest rows;
chest opening/check tracking and AP delivery continue through the normal bridge.
Without this override, Coliseum's vanilla Olympus table wins over the seed pak
and a chest can award both its original item and its AP item.

For `randomize` or `junk` cup rewards, the companion also clears all 437 reward
arrays in the mod's 23 cup reward tables. For `vanilla` cup rewards, it contains
only the chest override, preserving the mod's cup rewards. Cup mode therefore
never disables chest suppression while the full Coliseum mod is installed.

The builder verifies the full mod filename and accepted SHA-256, preserves all
chest rows and non-reward fields, then reopens the finished pak to verify every
chest reward is `NONE` and every requested cup reward array is empty. Both the
AP client and the PowerShell build helper use this builder. The helper accepts
`-PreserveCupRewards` to produce the chest-only companion.

The client records the built companion's hash and reward mode in an adjacent
`.pak.json` receipt. A mismatching companion must be rebuilt while KH3 is closed;
a failed build leaves the installed companion intact. The full mod remains
unchanged. The resulting load order is:

1. Official Steam `*_0_P.pak` files
2. AP seed pak (`_99_P`)
3. Single full mod `zzzy_ColiseumMod_998_P.pak`
4. AP companion `zzzz_APOlympusColiseumCompat_999_P.pak`

Do not remove or edit official Steam update paks. Never leave the original
`zzzColiseumMod.pak` active alongside the priority pak: mounting the full mod
twice caused unstable between-round package loading. The installer preserves
the original under a non-`.pak` disabled filename rather than deleting it.

## Seed option

The option follows the standard KH3 location-pool modes:

```yaml
Kingdom Hearts III:
  olympus_coliseum_pool: randomize # vanilla, randomize, or junk
```

- `vanilla` keeps every native reward bundle and adds no cup-clear AP locations.
- `randomize` replaces each cup's bundle with one unrestricted AP location.
- `junk` replaces each bundle with one AP location that cannot hold a
  progression item.

The integration intentionally models one check per cup (25 total), not one check
per item in a native reward bundle. The original mod grants 59 items across all
25 cups, and several cups share the same reward DataTable.

### Required Coliseum setting and access logic

For randomized/junk AP cups, set **Settings → Unlock Features → Series** in
the Coliseum menu. This native setting (value 1) opens the extra series before
beating the game while retaining each cup's story requirements. The default
setting locks every menu series except KH3 until the game is beaten, which
does not match AP's early-cup logic. **Series + Cups** (value 2) additionally
bypasses cup requirements; it is not needed for AP logic. No UE4SS override or
Blueprint pak replacement is required.

Every AP cup requires completing Olympus (Tornado Titan), including the secret
feather match. Cup-specific requirements are:

| Required completion | Cups |
| --- | --- |
| Olympus and Twilight Town | Phil; Pain and Panic; Hermes; Chef; Flan; Terra |
| Toy Box and Kingdom of Corona | Pegasus; Cerberus; Apollo; Ventus |
| Monstropolis and Arendelle | Hercules; Titan; Athena; Aqua |
| The Caribbean and San Fransokyo | Goddess of Fate |
| Base game / Master Xehanort | Hades; Gold; Platinum; Paradox; Zeus; The Story So Far; Infernal; Limit Cut; Vessels of Darkness |
| No additional story flag | Secret Sephiroth (feather interaction) |

Generation reuses each world's final encounter/event movement and combat rules,
as well as its portal requirements. These gates remain in effect when a world's
reward pool is vanilla. Postgame cups require the final boss location's access
rule, including the selected proofs/heart-pieces goal, so goal items cannot
logically depend on postgame cup rewards.

Verified against the source hash above: `MainData/KH1_Series`, `KH2_Series`,
`KH3_Series`, `MainData/Secret/Secret_Series`, and
`UserContent/Aproydtix_Series` and `BBS_Series` contain `UnlockGameFlags`.
World flags use 9999 except `gameflow_FZ >= 8820`; postgame uses
`gameflow_BT >= 100`. `ColiseumOverworldController` checks `gameflow_HE >= 9999`
for the entrance. `Menu_ColiseumMainMenu` checks `SettingUnlockFeatures > 0`
for extra series and `> 1` for cup flags. The English
`coliseum_strings.locres` labels these values **Series** and **Series + Cups**.

## Native Coliseum rewards

These are the completion bundles in the verified 1.4.2 pak. Shared rows are
listed together because the mod points those cups at the same reward table.

| Cup | Native completion reward bundle |
| --- | --- |
| KH1 Phil | Fencer's Earring; Wellspring Gem |
| KH1 Pegasus | Mythril Crystal; Writhing Crystal |
| KH1 Hercules | Star Charm; Orichalcum |
| KH1 Hades / KH2 Paradox / KH3 Zeus | Orichalcum+; Ribbon |
| KH1 Gold | Blizzard Cufflink; Dark Chain |
| KH1 Platinum / Secret Sephiroth | Crystal Regalia; Oathkeeper; Oblivion |
| KH2 Pain and Panic | Soothing Gem; Guardian Belt |
| KH2 Cerberus | Soothing Crystal; Power Band |
| KH2 Titan | Skill Ring+; Buster Band |
| KH2 Goddess of Fate | Orichalcum; Buster Band+ |
| KH3 Hermes | Skill Ring+; Midnight Anklet |
| KH3 Apollo | Forest Clasp; Mythril Crystal |
| KH3 Athena | Laughter Pin; Orichalcum |
| Apro Chef | Gourmand's Ring; Grand Chef; Hunny Spout |
| Apro Flan | Flanniversary Badge |
| Apro The Story So Far | Lucky Ring; Draw Ring; Master Belt; Petite Ribbon |
| Apro Infernal | Crystal Regalia+ |
| Apro Limit Cut | Breakthrough; Crystal Regalia+; Power Weight; Magic Weight; Master Belt |
| Apro Vessels of Darkness | Breakthrough; Crystal Regalia+; Royal Ribbon; Master Belt; Acrisius+ |
| BBS Terra | Fencer's Earring; Sinister Stone |
| BBS Ventus | Star Charm; Sinister Gem |
| BBS Aqua | Sinister Crystal; Petite Ribbon |

## Steam installation and manual fallback

For ordinary use, install the verified full mod once as
`zzzy_ColiseumMod_998_P.pak`, close KH3, and connect the KH3 client to a seed
using `randomize` or `junk`. The client creates the reward companion after it
creates or installs that seed's pak. Existing companions are reused and merely
enabled or disabled to match later seeds.

The repository script remains available to prebuild the companion or repair an
installation manually:

With KH3 closed, run from the repository root:

```powershell
.\scripts\build-kh3-olympus-coliseum-compat.ps1 `
  -SourcePakPath "C:\path\to\zzzColiseumMod.pak" `
  -GameModsDir "D:\Steam\steamapps\common\KINGDOM HEARTS III\KINGDOM HEARTS III\Content\Paks\~mods" `
  -InstallPriorityMod
```

The script accepts either the original source filename or the installed priority
filename, rejects modified content, copies the full pak byte-for-byte under the
priority name, builds the AP reward companion, and preserves differing installed
files with timestamped backups. Legacy original and duplicate-mirror paks are
renamed to timestamped disabled paths. No official `*_0_P.pak` is
removed or edited. The installer initially activates the reward companion; the
KH3 client then matches its active/disabled state to the selected seed mode. The
KH3AP UE4SS runtime must also be installed in the matching Steam game directory.

KH3 must be restarted after adding or updating a pak; a pak copied while the
game is running is not mounted into that existing process.

## How checks are detected

The runtime does not hook the mod's Blueprint controller or enemy kills. The mod
already writes authoritative progress to `ColiseumMod_Slot<N>.sav`. KH3AP's
existing KH3-scoped save-file observer queues that exact file after its write
handle closes, then reads each cup's saved `DifficultyBeaten` value. This avoids
adding UObject hooks or doing work inside combat and still distinguishes all 25
cups.

Cup completions are deduplicated and stored in a seed- and slot-scoped bridge
sidecar. AP item delivery waits until KH3 reports a trusted playable Sora
context after the results transition.