Importing Illusion Characters

This guide will describe the procedure to importing other illusion characters. There is no real order, I just do it the way I think is the most logical. The process is broken down into two main sections: the model and meshes section, and the bone frames and hitareas.

It is a fairly lengthy process compared to any of the other types of modding, but that is expected.
However, it is pretty straightforward.

I choose to import Illusion characters because all of the xx files are already set up for you (meshes, materials, textures, frames, bones, bone weights, UV's, normals, etc.) It is only a matter of setting it up so that you can load them in Yuusha. It is also possible to import characters from scratch, but you will have to first build the xx, and especially deal with the bones and weights and stuff. I don't know how that would be done.

So let's just stick with illusion models cause there's plenty to choose from (sexy beach series, artificial girl, hako, Characolle, etc)

Tools

SB3Utility 9.14+ (so you can rename frames without meshes properly)
PPextractor (get xa, kys, tty, and other files)
Quick Rename (for renaming frames and bones quickly, but I have not released it yet)
Hex editor

A: Loading the Model

The first thing is to verify that you can at least load the model. This is the easiest part and fairly straightforward. Refer to existing entries in any lst files if you are not sure where you need to edit stuff

1. Preparing the lst files

Depending on how thorough you want to be, the lst files you will have to edit will vary. The two primary lst files that will be modified are

• mo00_00_00_00.lst
• mo00_00_00_06.lst

To begin, we want to clear out 00.lst and 06.lst so we don't load anything that we don't want to load yet. This means going to the specific character entry and starting zero'ing out each value.

(If you don't understand the logic behind it, it is a useful technique when testing stuff. We want to make sure that things work one step at a time rather than try to put everything together and wondering where the error might be.)

For 00.lst, zero out everything except "01_01.xx" and "limb.lst". We will start with the clothed body.

For 06.lst, zero out everything except "a01_hip_010" and "a01_kokan_02" as these are required. You are simply keeping these for reference.

Since we are loading limb.lst, open it as well. You'll notice a number of lines referring to frame names. Most Since we don't want to load them, zero out each line except for the first line.

2. Setting up the xx files

We will be loading clothed and torn/nude models since they are the default behaviors in digital yuusha.
So first you want to look for the clothed model, copy everything into a new workspace, go to the 01_01.xx file that you will be replacing, delete all materials and textures, then replace the xx with everything in the workspace (hierarchy replace method: Replace)

Repeat this with a nude/semi-nude model for 01_00.xx, as well as the head 10_00.xx

3. Loading the xx files

To confirm that your xx files are correct, we start by loading the bodies. Note that you will be unable to switch between clothed and torn/nude until you load the head, so that is not important for now since it is a separate feature which we are not testing here.

You will have to do some lst editing again.
Go to one of the body xx files and look at the skeleton frames. You are interested in two frames: one that says "hip" (could be o01_hip, in the case of characolle), and another frame called "kokan02"

Copy these two names, go to 06.lst, and then modify the two values that you had left in step 1.
Then go to 00.lst and verify that the body xx files are in the correct spots (refer to the other entries if you don't know)

Pack the PP's and check that you can actually load the body.
At this point, you should be able to get the body loaded up.

4. Loading the head

To load the head, you will need the eyes file and the neck file (although I'm not sure what the neck file is for, it is not required)

The eyes file might come with the model. Some games don't, and I haven't successfully put one together yet, so choose a game that does have eyes files (characolle, eskmate).

Edit 00.lst to load the head xx and the eyes file.
If successful, your model should have both the body and head loaded, except the head is dark. This is expected, because we haven't defined how the head and body should be connected.

5. Connecting the head to the body

This step involves editing the plst files. You will need two: one for the clothed body, one for the nude body.

To edit a plst file, you can use enimaroah's plst encoder/decoder tool, or you can do it manually.
To do it manually, open it in a hex editor, select all values, XOR it with an unsigned FF mask, and then you should see some strings.

Modify them to point to the correct xx files and frames, then XOR it with the same mask again and save the file. Do this for both plst's, then add them to 00.lst.

If successful, the lighting on the head should look correct.

6. Adding facial animations

There should be an xa file that came with the model in the original game data (in the same PP you got the model from). Just add that to your PP and write its name in 00.lst

7. Adding wind effect

These are kys files. There are three of them: one for clothed body, one for nude body, and one for the head. The kys files should also come with the models.

B: Loading the hit areas

Now that your model is loaded, you will want to be able to move it right? This is where the hit areas come in. Note that you probably won't do any of this until I release QuickRename which will take in a text file that defines how frames should be renamed.

1. Building the frame mapping file

It is unfortunate that Illusion hardcodes a_hand.xa and s_hand.xa into the client, as these deal with all of the different poses. Consequently, if this file isn't loaded properly, none of the hit areas will show up.

Preferably, I would rather be able to specify which hand.xa file I want to use, but since we don't have that flexibility, we have to conform to the given standards. That is, rename all your frames, which led to my QuickRename script.

The first step is to print out the list of frames in your model's body. It doesn't matter which one you choose, since they are the same.

The bare minimum required is to change the finger frame names. So look for the five fingers (ko, hito, oya, naka, kusuri) and write the yuusha equivalent. Some games use names like "kyubi" and "oyubi". In this case, you match it based on the first letter. "ko" is usually written as "cyubi".

If you really don't know, you can always check the part that it corresponds to by rotating the frame and seeing which bone was affected.

Once you have completed the file as best as you can, you can run it through QuickRename and mass rename the frames.

2. Modifying limb.lst and hitarea.lst

You should create a separate limb and hitArea file for your new model and load it through 00.lst.

The easiest way to do this is to create a copy of a_limb.lst and HitArea.lst, rename it to something else, then go through each framename and make sure the names match up with what you have in the model's skeleton.

3. Modifying exp.lst

No idea what this is for, but it has an effect on the bone frames. Further investigation will be required. For now, fill in the first line that defines some neck bones, otherwise your character's head will be stiff.

4. In progress

There is still stuff to do. At this point, you will have imported the character and can move its limbs around, but there are still a lot of missing features.

C. Credits

Aside from myself for figuring out how all of it comes together,

Illusion, for models and client
enimaroah (hongfire) for decoding and providing tools for eyes, plst, kys, and tty files
Alamar (hongfire), for SB3U
Darkhound (hongfire), for the wizard and some notes
Any other users that have contributed models and model-related files for Digital Girl.