Patching KAG Games

By default, the KiriKiri game reads resources in the specified folder/archive sequentially. If a script is found later, it will overwrite the previous resource. The order of resource reading is as follows:

1. Data folder
2. data.xp3
3. patch.xp3
4. patch2.xp3
5. patch3.xp3
6. patch4.xp3
7. … and so on…

For example, if there is a “first.ks” scenario in the Data folder, it will be overwritten by the “first.ks” in data.xp3. Similarly, the “first.ks” in data.xp3 will be overwritten by the version found in patch.xp3, and so on.

This behavior allows us to create translations without modifying the original data.xp3 file or any of the original assets in the game. Instead, we can create a patch.xp3 file.

Thus, there are at least two ways to inject mods or apply translations using the KiriKiri engine:

First way of applying translation: Extracting data.xp3 into the data folder

1. Extract the contents of data.xp3 into the data folder.
   • Various tools such as GarBro or KrkrExtract can be used to extract xp3 files.
2. Inject or apply your translation.
3. Important: Remove the original data.xp3 file. This ensures that the game will load the data folder instead.

Second way of applying translation: Creating patch.xp3

To repack the translated materials back into an xp3 file, you can use the Translator++ xp3 repacker tool. Here’s how you can create an xp3 patch:

1. Export (not inject) your project into a blank folder.

2. Open the Translator++ XP3 repacker tool and select the directory you created in the previous step in the “Select directory” field. Also, select the target xp3 file.

Note: The naming of the xp3 files matters, as the content of patch2.xp3 will overwrite patch.xp3, and so on.

3. Click “Process” and wait until the process is completed.

4. Copy the newly created xp3 file into the root folder of your game.

Understanding the Structure of patch.xp3

By default, Kirikiri only reads data in the root directory of the patch.xp3 file. This can result in an ugly internal structure, as all data including images, tjs, and scenarios are collected in one folder. Moreover, it does not allow files with the same name that were previously in different folders.

However, there is a way to make the KAG engine read the folder structure within patch.xp3. This can be achieved by adding a definition in the Config.tjs file.

Here’s an example of the patch’s structure definition inside Config.tjs:

// Config.tjs - KAG 設定
// Copyright (C) 2001-2007 W.Dee and contributors  改変・配布は自由です
;global.config_version = ""; // この行を消さないでください

// このファイル内で設定できる項目は、すべて
// ;設定名 = 値;
// の形式になっています。
// 「追加の設定」を除いて、設定は各項目につき１行で記述する必要があります。

Storages.addAutoPath(System.exePath + "patch.xp3>fgimage/");
Storages.addAutoPath(System.exePath + "patch.xp3>fgimage_other/");
Storages.addAutoPath(System.exePath + "patch.xp3>fgimage_renamed/");
Storages.addAutoPath(System.exePath + "patch.xp3>image/");
Storages.addAutoPath(System.exePath + "patch.xp3>scenario/");
Storages.addAutoPath(System.exePath + "patch.xp3>system/");
Storages.addAutoPath(System.exePath + "patch.xp3>video.xp3/");

By including this definition, you can create a patch.xp3 file with its original folder structure.

Remember to move the Config.tjs file to the root directory (originally located in the system folder), as Config.tjs is read before the Kirikiri engine gains the ability to read folders.