UI Compiler

Scripts for easier editing of Unity assets for Higurashi.

The main rust script will generate a new emip file, apply it to the assets and pack the assets into 7zip archive we need for a release.

Documentation Notes

Please note that documentation is in two places:

This Readme.md file (for basic usage information)
Detailed documentation with images etc. on our Wiki.
- You don't need to read all of this to use the tool!

Instructions for Translators

Overall, the workflow for translators is:

Setup your computer to run our tool, including cloning or forking this repo
Modify/replace the files in the repo with your translated versions
Run our tool to generate the .assets and .languageSpecificAssets files you can include in your release

Please continue with detailed instructions below.

Setup (Windows Only)

The below instructions only work on Windows!

Follow the instructions here to install Python 3, and make sure Python is on your path
- If the above link doesn't work, just make sure you do the following:
- During the install, make sure you tick the checkbox "Add Python 3 to PATH"
- After the install is finished, open a fresh command window, then type python to check if python is correctly on your path (should display the python prompt)
For translators, fork this repository (Github forking instructions)
- A fork is recommended for translators as you can check in your changes to github. It also allows you to use Github for building and hosting assets
Clone the repository (either this repository, or the one you forked) to your computer

Modifying images, text, and fonts

To modify images

To modify images, replace the image files in the assets/images folder.

Folder info:

images/shared: images common to all chapters
images/question_arcs: images specific to chapters 1-4
images/answer_arcs: images specific to chapters 5-8
images/specific/[CHAPTER_NAME]: images specific to a particular chapter
images/version-specific/[CHAPTER_NAME]: images specific to a particular chapter + unity version combo

Make sure have a quick look at all the folders before starting work, so you don't miss any images by accident.

To modify text

The game contains various text which is not contained in the game script or the DLL (it is stored directly in the .assets file). This text is also not stored as image files, so you can't edit an image to change it.

To edit these text files, edit the assets/text-edits.json file. Please read https://07th-mod.com/wiki/developer/sharedassets/ui-editing-scripts/#unitytextmodifier for more details on how to edit this file.

To modify fonts

To modify fonts, see

For Chapters 1-8: https://07th-mod.com/wiki/developer/sharedassets/ui-editing-scripts/#adding-font-support-for-a-new-language-chapters-1-8-only
- Note: Due to some Unity plugins being no longer supported, you may have trouble following these instructions. Please let us know if you have problems and we'll try to sort it out.
For Chapter 9 https://07th-mod.com/wiki/developer/sharedassets/ui-editing-scripts/#adding-font-support-for-a-new-language-higurashi-rei-onwards-only

Fonts are stored in the assets/fonts folder as *.dat files, with the exception of Rei where fonts are stored in the assets/files-2019.4 folder.

To modify other files

The assets/files-[UNITY_VERSION] folders contain files applied to a particular Unity version, regardless of chapter. You normally don't need to modify these files.

Currently these folders contain higher quality caret sprites (the little cursor/triangle displayed at the end of a text line), with the exception of the assets/files-2019.4 folder which also contains fonts for Higurashi Rei.

Avoiding installing python packages globally (optional)

The build.py script will automatically install the packages in requirements.txt globally.

If you do not wish to install globally, create virtual environment before running the program:

# Create a new virtual environment in the `venv` folder
python -m venv venv

# Activate the venv in cmd.exe
venv\Scripts\activate.bat
# OR Activate the venv in PowerShell
venv\Scripts\Activate.ps1

# Now your shell should be prefixed with `(venv)`

# Run the script
python build.py onikaushi

Make sure to activate the venv every time you want to run the script.

Generating .assets and .languageSpecificAssets files (Windows Only)

To list the supported Higurashi chapters for this tool, run

python build.py

which should show an error message and list available chapters

Then run

python build.py onikakushi

Then the output files will be located in the output/translation folder. You can then merge the HigurashiEp0X_Data folder with the one in your release. Please include all the files (not just the sharedassets0.assets file), so the installer can select the correct file at install time.

If you want to rebuild all chapters, run python build.py all to build all chapters.

Common Problems

You may encounter the following problems:

Windows Defender may block/delete our precompiled ui-compiler.exe. In this case, you can either try to unblock it, or install Rust to make the script compile it on your own computer. Contact us if you have this issue.
For any other error, likely we just need to update the build script, so please contact us.

Updating dependencies

NOTE: The script should automatically detect if the vanilla assets or UABE has changed, and re-download them. But if that doesn't work, use the '--force-download' option like so:

python build.py rei --force-download

Instructions for Dev Team

Instructions are the same as for translators, but archive files will be automatically created in the output folder

Modifying Assets

Assets are located in the assets folder. Replace any file in the assets folder, then run the script again, and it should be included in the generated assets files.

Building assets using Github Actions

Note for forks/translators

Github actions might be disabled for your forks. Clicking on the 'Actions' tab should allow you to enable it. Please do this before proceeding.

Triggering Github Actions Builds

Building a release

To use Github Actions to build a release, create a tag like v1.0.6_onikakushi which contains the chapter name (separated by an underscore) you want to build (or 'all' for all chapters).

Click on the 'Actions' tab to observe the build process.

Once the build is complete, go to the 'Releases' page, and a new draft release should appear. You can check everything is OK before publishing the release, or just download the files without publishing the release.

Note that doing this will build both the translation.7z file for translators to use, and also the individual archives for the 07th-mod developers to use.

Building `ui-compiler.exe` using Github Actions

To build just the ui-compiler.exe using Github Actions (on Github's server), push any tag to the repository.

New Episode Preperation Instructions

The following information is only used when adding support for a new episode.

Please look through the detailed documentation, especially if you're working on a new chapter, new language, or using UABE - this file does not contain information on those topics.

WARNING about Unix/MacOS `sharedassets0.assets`

We've found that the MacOS sharedassets can be used on Linux, but the Linux sharedassets CANNOT be used on MacOS in certain cases, giving you the "purple text" issue.

For this reason, whenever a new chapter is prepared, the 'vanilla' unix sharedassets0.assets should be taken from the MacOS version.

Initial dumping of textures

You will initially want to inspect all the textures in the UI file to see if any new images need to be added to the assets/images/* folders.

Open and select the sharedassets0.assets AND the sharedassets0.assets.resS from the new episode in UABE
Click the "Type" column to sort by "Type"
Scroll down until you see "Texture2D"
Hold shift, then click the first "Texture2D" item
Continue holding shift, then click the last "Texture2D" item. This should highlight all the "Texture2D" items.
On the right hand side, click "Plugins"->"Export to .png"

The textures will be dumped as images in the selected folder. However please note:

You will need to rename them by keeping the first part of the name only - for example ChapterPreview-sharedassets0.assets-27.png becomes ChapterPreview.png
It is also possible to use the number (Path ID), but usually you won't do this. In the above example, rename as 27_ChapterPreview.png (the part after the number is not used, only to describe the file for humans)
Make sure you put them in the right subfolder in assets/images, refer to "To modify images" section for details

Preparing font files

You'll need to extract the 'msgothic' font files from the stock .assets file before starting:

Open one of the sharedassets0.assets from the new episode in UABE
Find two font files (search for *msgothic* and hit F3 a couple times). Note there are other files with msgothic in the name, you're looking for ~100kb files with the exact names below:
- MonoBehaviour msgothic_0 SDF
- MonoBehaviour msgothic_2 SDF
Click "Export Raw" and save the files to disk
Rename them as msgothic_0.dat and msgothic_2.dat
Move them to assets/vanilla/<chapter>/msgothic_0.dat & assets/vanilla/<chapter>/msgothic_2.dat

Fixing Caret (Ch.9 onwards)

It appears the caret Sprite files need to be modified slightly, but otherwise can be copied between chapters. The caret textures (.png files) don't need to be modified.

To do this:

Extract the caret Sprite files as .txt from Ch.9. There are 3 for each type of caret (clickwait, and pagewait carets)
Compare the two files in Winmerge or similar
Copy the 0 SInt64 m_PathID value from the vanilla caret Sprite file to the mod caret Sprite file. This ensures the correct texture is referenced.
Now we need to convert the .txt back to .dat. To do this, open the modded sharedassets, then click "Import Dump" and import the fixed caret files, overwriting the appropriate sprites. Then click "Export as Raw" to get the .dat files usable
Place the caret files in the assets/files-[game_name] folder.
- Note that each time a new game is released, you will need to update the Rust script to handle the new game, and reference the assets/files-[game_name] folder so it knows where to copy caret/fonts from.

Extra Notes

If you want to use this tool to compile assets for a different language, you can change the files in the assets directory to your needs.

Developer Notes

Documentation for the underlying python scripts can be found here.

Manual Setup and Running Instructions (Windows Only)

We suggest using the above python script intead to setup everything, but these instructions remain here for reference.

These instructions do not rely on the build.py script, and are roughly how we ran the ui-editing-scripts before the build.py was created.

Note: these are rough instructions only, and may need updating.

Install Python 3
Run python -m pip install -r requirements.txt (or python3 instead of python), to install the python dependencies
Download the vanilla assets from our website, then extract them to the root of the repository (the assets folder in the archive will merge with the assets file in the repository)
Download and extract UABE somewhere, then make sure AssetBundleExtractor.exe is on your path
Decide whether you want to get the pre-compiled executable, or compile the executable yourself (see below):

Option 1: Getting the pre-compiled executable

Download the pre-compiled ui-compiler.exe
Make sure it is on your path, or in the root of the repository

Option 2: Compiling the exe yourself

Follow this guide to install Rust on Windows There are some gotchas for Windows (like you need to install Visual Studio before installing rust).
In the root of the repository, run cargo build to check everything works correctly.

Running ui-editor-scripts

To compile a particular chapter/variant, open build.py and look at the valid chapters, for example:
- onikakushi 5.2.2f1
- matsuribayashi 2017.2.5 unix 51100D6D
Run cargo run (compile yourself) or ui-compiler (pre-compiled) with the command you chose earlier. Following the previous example:
- cargo run onikakushi 5.2.2f1
- cargo run matsuribayashi 2017.2.5 unix 51100D6D

If you compiled the exe yourself, you can run the ./compileall.sh under windows by using git bash which comes with Git for Windows.

07th-mod/ui-editing-scripts