Plants vs. Zombies 2 Hacking Tools/Taiji

*WIP community effort! Feel free to edit if something is wrong/outdated*
**Taiji** (simplified: **太极**; traditional: **太極** *tàijí*, formerly **SPCUtil** or **SPC-Util**) is a tool designed for decoding and reencoding the custom file formats found in the assets of Plants vs. Zombies 2. It is developed by SmallPC website

The tutorials here are written for

* **version 1.5.0** of the Taiji loader (updated 2020-10-??)
* **version #3.11.0$public** of the Taiji core (updated 2020-11-03)

Windows tutorials will use filepaths which assume you are using the C drive `C:\`.

## External links

* Official site (contains downloads and some tutorials for setup, albeit in Mandarin)

## See also

* Plants vs. Zombies 2 Hacking Guide/OBB and RSB file structure - an overview of the OBB and the special file types mentioned here.

## Setting up Taiji

### Windows

When working with files, Taiji may attempt to access files that are supposed to be at specific locations. Setting up the environment for Taiji is a matter of downloading all these needed files and placing them in the expected locations.

Taiji uses the current drive to locate files.

#### Prerequisites and materials

* Microsoft Visual C++ 2015-2019 Redistributable: This is required for the loader to run. It is likely already installed on your device by default. (If it is not, attempting to run the loader will show a dialog box telling you to install this.)

Downloads from the official site:

* `太極-Loader.exe` (64-bit) or `太極-Loader-32.exe` (32-bit); the "loader".

#### Update Taiji

1. **Run the loader.** Running the loader with no input while in the C drive will prompt Taiji to show the download interface. Press any key, and it will download all the needed files. (If you are running the loader at `C:\ProgramData\cn.smallpc\taiji\loader.exe`, you may need to rename or move the loader to let it download.)
	* *According to the Taiji website, new versions of the loader past version 1.5.0 will not be downloaded automatically. Since there hasn't been a new version since 1.5.0, it is uncertain if this will be the case.*
	* The files will be downloaded under `C:\ProgramData\cn.smallpc\taiji\`. The directory will directly contain the newest version of the Taiji loader `loader.exe` (if the downloaded loader is outdated), the "core" `taiji.dll` which Taiji will access, and `env.json`.
2. If there is not a new version of the loader, you will have to move the loader to `C:\ProgramData\cn.smallpc\taiji\` manually. Otherwise, you can safely delete the old version of the loader. Rename the loader to `loader.exe`.

Now, all the files should be present and located where they need to be.

#### Connect external applications

In order to extract and decode WEM files, you need to supply `ffmpeg.exe` and `ww2ogg.exe` for Taiji to run when necessary.

1. **Create a new directory at `C:\ProgramData\cn.smallpc\taiji\extern\`.** Taiji will look for this directory for external applications.
2. **Download FFmpeg.** Several ZIP builds will be available, but all of them, apart from ones reading `vulkan` or the source code ZIP, will work.
3. **Extract the FFmpeg ZIP and find `./bin/ffmpeg.exe`. Copy it to `C:\ProgramData\cn.smallpc\taiji\extern\`.**
4. **Download ww2ogg (ww2ogg024.zip).**
5. **Extract the ww2ogg ZIP and locate `ww2ogg.exe` and `packed_codebooks_aoTuV_603.bin`. Copy them to `C:\ProgramData\cn.smallpc\taiji\extern\`.**

Taiji should now be able to successfully decode WEM files.

#### Add to right-click menu

If you want to input files or directories to Taiji without having to drag them onto the loader every time, you can instead add Taiji to the right-click menu.

To do this, navigate to `C:\ProgramData\cn.smallpc\taiji\other\` and double-click `windows.shortcut.reg` to merge the registry keys. To undo this, double-click `windows.shortcut-remove.reg`.

After merging the registry keys, when you right-click a file in Windows Explorer, you should see an option called "太極-QE" (and, for some file types, "太極-QE : **`<file type>`**"). These options will launch Taiji with the right-clicked file as input.

## Processing files with Taiji

The special file types in Plants vs. Zombies 2 each have different operations that Taiji can apply to them. For example, RTON files have the option to be decoded into JSONs, and JSON files back into RTONs. PAM files can be decoded into XFLs, and PTX files can be decoded into PNGs. (All files will have the option to be z-lib compressed or xor/base64 encoded/decoded.)

### Windows

**Note: Processing files depends on the month. If the month of the Taiji version used is behind the current system month, then Taiji will crash upon being passed a file. To get around this, set the system time to Taiji's month before passing in a file. *(As of December 28, 2020 (version 1.5.0), there has not been a new version of Taiji in December. This means you will need to set the system time to November 2020 (optimally in the middle of November, due to time zone issues) before passing in a file. You can change the system time back afterwards.)*** You can also use RunAsDate to run Taiji without changing the system time.
To pass a file to Taiji as input, drag it onto the loader in Windows Explorer. Any file or directory can be supplied, and different operations will be shown for different file types.

Directories can be treated as a container for files that should have the same operation applied to them all at once (a batch operation). Sometimes, however, it will be necessary to use a directory as a particularly structured collection of files for certain tasks. For example, reencoding an XFL and its library contents into a PAM or packing modified OBB contents back into the OBB requires passing in the relevant directory. Passing in a directory will prompt Taiji to ask "`is batch-mode ?`". Answering `1` will have Taiji prepare a batch operation, and `0` will have it provide the context-specific options.

Most decode/encode operations will create a new file in the directory of the input file, without altering the input file.

#### Selecting options

Taiji is a command-line application, and you can select options or provide arguments to an operation by typing into the command line prompt when asked to.

When shown the set of operations that can be applied to a file, type the number next to the operation you want to be performed.

If no further action is needed, it will perform the action and wait for you to press a key for the window to close. If Taiji needs more information, it will ask for some arguments for you to type in. Taiji will give a brief description of what it needs (like an image width, or an option written as a question), alongside the expected type of the input. If Taiji asks for a `Bool`, then the option is a yes-or-no switch; `1` means yes, and `0` means no. If it needs an `Int`, then you need to supply an integer. Taiji will also sometimes ask you to select a file containing the information it needs.

## Unpacking or extracting from an OBB/RSB

OBB or RSB files contain the assets for Plants vs. Zombies 2, such as images, sounds, animations, and data about levels, plants, zombies, and more. Taiji provides the option to access all of these files for editing, and then repack these modifications into a file that Plants vs. Zombies 2 will read.

### Windows

#### Prerequisites and materials

* Taiji is setup.
* The OBB/RSB file to be extracted from

#### Process

1. **Pass the OBB/RSB file as input to the loader.**

You will be presented with the operation menu for OBB/RSB files.

`unpack` (or `unpack-for-work`) will extract undecoded files which you can decode and edit and which can be later repacked into the OBB/RSB. `res-unpacker` will also extract all the undecoded files, but it will also provide options to decode RTONs, textures, animations, and sounds into more easily viewable formats immediately.

Both of these options will extract to a directory named after the OBB/RSB with ".dir" appended to the end. No matter which unpacking operation you select, the undecoded assets will be extracted under `**<OBB/RSB filename>**.dir\res\`. Note that some file or directory names may be different from when unpacking with a different app (i.e. filenames won't be all uppercase).

* unpack-for-work (Prepare for modding)
* res-unpacker (Decode and view game assets)

1. **Select the `unpack-for-work` option.**

You will be prompted for arguments:

Taiji will now extract the files.

*WIP*

1. **Select the `res-unpacker` option.**

You will be prompted for arguments:

*Answering `1` may cause the operation to fail. Taiji will try to access the `:RTON:Encryptor:DeCrypt` function, which is currently kept private to the developer.*
 `decode texture to png ?` (Bool)
 `select texture-format-index-mapper-file for decode-atlas` (Path\_File)
 `decode pam file ?` (Bool)
*Answering `1` may cause the operation to fail. Taiji will try to access the `:Anim:PopcapAnim:Encoder:DeCode` function, which is currently kept private to the developer.*
*Answering `1` will cause the operation to fail if you have not yet connected FFmpeg and ww2ogg.*

Taiji will now extract the files.

Depending on which types of assets you chose to decode, additional directories will be made under `**<OBB/RSB filename>**.dir\` to contain the decoded assets:

* `./atlas/` for unsplit texture atlases
* `./image/` for sprites split up from the texture atlases
* `./audio/` for audio from `./streamingwaves/`
* `./json/` for JSONs extracted from `./packages/`
* *TBD*

**Note:** During extraction, you may run into an error regarding `RESOURCES.RTON`. If this happens, go into `**<OBB/RSB filename>**.dir\`. Then, rename the folder `PACKAGES` to `packages`, and within `packages`, rename the resources RTON file to `resources.rton`. You can then run `res-unpacker` again.
With the files extracted, you can now access/view all the assets in the game.

The working directory will appear as follows:

* `**./**` - The unpack result directory.
	+ `**res/**` - The directory containing the undecoded assets from the OBB/RSB.
	+ `**packet/**` - *TBD.*
	+ Any decoded asset directories, listed above in the `res-unpacker` tab.
	+ `**infoX-ori.json**` - A decoded copy of `./res/properties/resources.rton`.
	+ `**infoX.json**` - A copy of the information given in `./res/properties/resources.rton`, but presented in a more concise object format.
	+ `**info.json**` - A file which organizes all the resource and audio groups in object format.

## Packing back into an OBB/RSB

### Windows

#### Prerequisites and materials

* Taiji is setup.
* The unpacked OBB/RSB directory
* You have made whatever modifications you would like to the files under the `**<OBB/RSB filename>**.dir\res\` directory.

#### Process

1. **Pass the** `<OBB/RSB filename>**.dir\**` **directory as input to the loader.** Type `0` when prompted "`is batch-mode ?`".

`pack-for-work` tends to take a fraction of the time as `pack`. The difference between them *TBD*. (If one doesn't work, try the other.)

* pack-for-work
* pack

1. **Select the `pack-for-work` option.**

You will be prompted for arguments:

*Entering either `0` or `1` will work (`0` is faster).*

1. **Select the `pack` option.**

You will be prompted for arguments:

 `export-new-packet ?` (Bool)
 `use-ready-packet ?` (Bool)

Taiji will now reconstruct the OBB/RSB. When it is finished, you will have an OBB/RSB that Plants vs. Zombies 2 will be able to read from.

You may notice that the new OBB/RSB may have a different file size from before. This is OK; Plants vs. Zombies 2 can still read it.

## Other file conversions

Note that `res-unpacker` when extracting from an OBB/RSB can perform applicable conversions for all files in the OBB/RSB.

### Windows

#### Prerequisites and materials

* Taiji is setup.

Applications that can read/edit the target file types include:

* **PNG:** most image viewers/editors.
* **JSON:** any plain-text editor (e.g. Notepad, Notepad++).
* **WAV:** most audio players (e.g. QuickTime Player, VLC).
* **XFL:** (e.g. Adobe Animate).

#### RTON to JSON

1. **Pass the RTON file as input to the loader.**
2. **Select the `decode` option.**

*Encrypted RTONs (from a Chinese RSB) are currently not decodable.*

#### JSON to RTON

1. **Pass the JSON file as input to the loader.**
2. **Select the `encode` option.**

#### PAM to XFL directory

1. **Pass the PAM file as input to the loader.**
2. **Select the `convert-to-xfl-onestep` option.** *`decode` will not work here since the `:Anim:PopcapAnim:Encoder:DeCode` function is missing.*

There should now be a new folder in the current directory, with the name of the XFL. Inside the folder is the XFL itself and a directory named `LIBRARY`. In order for textures to show up in the XFL animation, you must copy the split images from an `res-unpacker` extraction into the `LIBRARY` folder.

#### XFL directory to PAM

1. **Pass the XFL directory as input to the loader.** Type `0` when prompted "`is batch-mode ?`".
2. **Select the `convert-from-xfl-onestep` option.**

*Note that saving the XFL with Adobe Animate may modify the directory into a state which Taiji can no longer parse correctly.*

#### PTX to PNG

1. **Pass the PTX file as input to the loader.**
2. **Select the option for decoding using the appropriate compression format for your platform.**
	* For Android international, use "RGBA32" or "ETC1+ALPHA".
	* For IOS (both international and Chinese) use "ARGB32" or "PVRTC-4BPP"
	* Android Chinese's alpha format is still unknown, so decoded images will not have transparency. You still can use "RGBA32" format (file size is too large).

You will be prompted for arguments:

The `resources.rton` file extracted from the same OBB/RSB as the atlas will provide the widths and heights of all the atlases. You can find it by decoding `resources.rton` and searching for the atlas filename without the file extension. Find the object that refers to the atlas's file path. This object provides the width and height of the atlas.
You can also find dimension information by opening either of the "info" files Taiji generates when unpacking an OBB/RSB (listed above) and searching for the file in a similar manner.

*If the correct format and dimensions are not chosen, the loader will crash. Simply try again with a different format or after checking that the dimensions are correct.*

#### PNG to PTX

1. **Pass the PNG file as input to the loader.**
2. **Select the option for encoding using the appropriate compression format for your platform.** See formats above.

#### BNK to WEMs

1. **Pass the BNK file as input to the loader.**
2. **Select the `unpack` option.**

There will now be a new folder in the current directory, named the filename of the soundbank with ".dir" at the end. In this directory, you can find the extracted WEM files under the subdirectory named "`DATA`". Alongside this subdirectory are files that tell the structure of the BNK before it was extracted, so that Taiji can repack the BNK later.

#### Repack to a BNK

1. **Pass the unpacked BNK directory as input to the loader.** Type `0` when prompted "`is batch-mode ?`".
2. **Select the `pack` option.**

#### WEM to WAV

1. **Pass the WEM file as input to the loader.**
2. **Select the `decode` option.**

This conversion will not work for Chinese iOS WEMs (they do not use Vorbis compression); for those, vgmstream can be used instead.

#### Unpack an RSB.SMF

Currently, Taiji does not seem to be able to do this alone. However, QuickBMS is able to get an RSB from an RSB.SMF, which Taiji can then process.

You can use QuickBMS on the RSB.SMF the same way you would with an RSB or OBB, using the QuickBMS application and the BMS script file prepared by the creator of QuickBMS. After processing the RSB.SMF, you can find the RSB directly in the result folder.

## Applying a premade patch package

Several premade mod packages (ZIP files with "tjpvz2mod" (Taiji PvZ2 mod) in the filename) are available on the Taiji website that can be applied to an OBB/RSB to make predesigned modifications to it.

*TBD.*