Tutorial SSMOD installer - English

Tutorial created by eternity in Anime Game Mods Forum.

This tutorial will teach you how convert "normal replacer mods" (non tpf mods) into "new character" mods (.ssz) that can be installed by SS Mod Installer. Requeriments: a mod that have at least an .emo or .emb file; notepad++. (no, please, DON'T use the notepad that comes with windows to write the xml), and an archive program that can make .zip files (Winrar, winzip, 7-zip, etc).

The guide is primarily intended for modders wanting to create mods in .ssz format, but it could also be used for users that want to convert those mods to .ssz format if the modder doesn't provide one.

The guide will use as example converting "Evil Saga with god armor" to the .ssz format.

SSZ Format

First of all. What are the .ssz files that SS Mod Installer uses? .ssz files are nothing more than .zip files renamed with the .ssz extension, with a .xml file inside called "sszmod.xml"

with all the information needed to create the new character, the four main files of a character models (.emo, .emm, .emb and .2ry), and optionally a folder called "resource" that contains additional files in case the mod needs them (such as custom effects, etc)


In case you are wondering why I'm renaming an existing format extension, there are two good reasons (and none of them are "because it is cool"):

1: If the mods used the .zip extension, they would confuse users, because they would think they need to extract the .zip file. By using the .ssz extension, this prevents accidental extraction. The problem becomes worse when you want to have a collection of mods in .zip format. Let's say I want to package all my Hildas in zip format. And the .zip containts several .ssz files inside. That's fine, the user extracts that .zip and then install the .ssz files inside. Buf if I hadn't renamed the .extension, it would have been a .zip file with other .zip files inside, and the brains of most users would explode with that.

2: To distinguish the files from regular .zip files and have a dedicated extension. A regular .zip file may contain or not contain the xml, or other info. A .ssz is supossed to contain that info. This would prevent the user from trying to install .zip files that don't really contain mod information, the user will know that a mod is a mod for SS Mod Installer if it has the .ssz extension.

Step 1: preparing the main files

Create a folder somewhere and call it whatever you want. You will be using this folder for the rest of the guide. Copy inside the .emo, .emb, .emm and .2ry of the mod. If your mod doesn't come with one of these files (for example, if your mod only replaces textures and only comes with an (.emb), you can get the remaining files from the game files (extracted resource.cpk)

Remove the "_00", (or any other number from the file names). In our example, we rename the files SGG_00.emo, SGG_00.emm, SGG_00.emb and SGG_00.2ry to SGG.emo, SGG.emm, SGG.emb and SGG.2ry.

Step 2: writing the basic information of the xml

Open Notepad++ and create a new file (file->new). Before even doing anything, save the file as "sszmod.xml" in the folder where you have the other files. Now go to encoding menu and set "Encode in UTF-8 without BOM".

Now paste the following text into the file: 

<?xml version="1.0" encoding="utf-8"?>
<SSZ> <SSZ_FORMAT_VERSION value="1.2" />
<MOD_NAME value="" />
<MOD_AUTHOR value="" />
<MOD_VERSION value="" />
<MOD_GUID value="" />

<CMS_ENTRY value="" /> 

 </SSZ> Now I will be explaining every value with detail.

SSZ_FORMAT_VERSION:This is the version of the .ssz

format. Put 1.2 here, which is the latest version. This value serves two purposes:


- To avoid older version of SS Mod Installer from trying to install your mod (which may use features that are only available in a later version) and instead display a message about that. - If the format changes, the internal code of future versions of SS Mod Installer will need to know the format version, so that it can still support older mods.


So, when in doubt, just always specify what this guide tells you, which in this case is 1.2.

Note: some of the linsk to pastebin here are a bit outdated and show version 1.0. This is because I was too lazy to update, but you should just specify 1.2.

 

MOD_NAME:
This is the name of your mod. This is not necessarily the name of the character (although usually you will want to call it like that). This value is only used by SS Mod Installer, to display that information to the user. This information will also be used in the machine-generated comments of the game xml files (cmn_model_spec.cms.xml, slots_data.slf.xml, etc). But it won't be used by the game at all. As of current version, there is no way to specify a specific new character name for the game. But in the feature, when this feature appears, it will use a separate value, not this one. This value will remain always only to identify the mod in a user-friendly form.


In our example, we write:

<MOD_NAME value="Evil Saga with God armor" /> MOD_AUTHOR: If you're the author of the mod, you should put your name in there. Otherwise, put the name of the mod author. In our example, we write:

<MOD_AUTHOR value="eternity" />                                                                

MOD_VERSION:This is the version of the mod. Initially you would usually set it to 1.0 (although you may put whatever you want, like 199.0 :p). And increase in the way you want in future versions. SS Mod Installer will use this information to let the user update the mod in the same slot they initially used. So it is important that you increase the value with every new version of your mod.

How you increase it, is up to you.

In our example, we write:

<MOD_VERSION value="1.0" />                                                                         

 

MOD_GUID: This is a very important field.A guid is a 128 bits number used to uniquely identify something. In this case, SS Mod Installer identifies mods by the guid, not by the name (the name is purely cosmetic, for the user). For example, two modders may call their different mods "Black Pegasus", but it is the guid what SS Mod Installer uses to know they are actually different mods. Go to this page and click on "generate some GUID". And just paste the value.Whenever you update the same mod, you must keep the same guid.Otherwise, SS Mod Installer won't know it is a new version of the same mod. Of course,for every different mod (different character, even if it is is a different variant), you should use a different guid.

Please, don't have the "brilliant idea" of generating the guid yourself using something dumb like 0000000-0000-0000-0000-000000000000. Use the page provided to generate it.

In our example, we write:

<MOD_GUID value="0a363ca3-b8b7-4fd7-b45f-800ed792f70b" /> CMS_ENTRY: Set this value to the same base name as your .emo/.emb/.emm/.2ry.In our example, this would be "SGG". You may be tempted to write your own values that don't exist, like "EVIL_SAGA".Don'tdo that. This value must be an existing value. Like ATG, SEY, SGG, etc, which also matches an exiting folder name of the game. You should know two things:

1: whatever you specify here, it will be the folder where the installer will install your main files (emo, emb, emm, 2ry).

(The final names of these ones are calculated by the installer, to avoid collision with game files or other mods). 2: The game will position itself in this directory when loading your character. This is important because some of the relative paths of the ModelSpec entry are relative to that folder.


Anyway, whatever you specify, it must match the name of the .emo/.emb/.emm/.2ry

that you put in step 1.


But if that was too much info (sorry), just use this logic: "the mod had a file called DSE_03.emb" -> "DSE"; my mod had a file called "SNA_00" -> "SNA".


In our example, we write:


<CMS_ENTRY value="SGG" />                                                                  


So, after finishing this step, our .xml file looks like this.

Step 3: writing the character info in the xml.

Now it is where we will write the real information that the game will use for our character. Don't worry, most of the time we will just be copy-pasting things from the game .xml files.  

Step 3.1: the ModelSpec.

So,you may have noticed that folder called docs that is in SS Mod Installer directory. That folder contains original game files decompiled in .xml format and with some nice machine-generated comments. You should treat these files as if they were read-only, you won't modify anything in them, you will just be copy-pasting values from here to the sszmod.xml file, and any modifications will be done in your sszmod.xmlfile.

So, open the file cmn_model_spec.cms.xml, and search for your character model spec. If your replacer was replacing DSE_02, then search for "DSE_02". You will also find the original character name next to it. Select the full ModelSpec that is below. (this is anything from <ModelSpec> to </ModelSpec>, including both tags), and copy paste it to sszmod.xml.

(just after the line of <CMS_ENTRY..., in a new line)


Now, let's remove some entries from here: remove "<EMO", "<EMB", "<EMM", "<TWORY", "<IDX" and "<MODEL_ID". Let me explain why are removing these (and this explanation is also true for the next steps, for whenever I say to remove something). These all are entries that must be calculated by the installer, to avoid conflict with other mods and with vanilla characters. For example, the installer will chose the final name of the .emo, .emb, etc files by appending a number to it, and the installer will make sure it doesn't conflict with any other mods. And same goes for the other files, and most importantly, for IDX and MODEL_ID, which are two very fragile values that just can't be left to a human.

If you don't remove these, nothing will happen. The parser will ignore them anyway. But for the sake of not having things in the xml that are not gonna be used, we are removing them.


What can you customize from here? Well, remember the guide about changing the aura? You could do that here. Note, however, that the field "U_DC" is not longer there because it has been renamed as COSMO. We will not be doing it in our example, but if you want the cosmo and aura of other character for your new character, just find their values and put them here.

In the ModelSpec, we can also do some other things, like changing the effects, although that also needs you to put files in a resource folder.... but that will be addressed in Step 4.

So, after finishing this step, our xml looks like this.

Step 3.2: the ModelEntry

This time open the file chara_data.cdc.xml. Find like before the entry of the character in which yours was based. And copy paste from <ModelEntry> to </ModelEntry>

Now delete the id= "..." thing, so that the line stays like "<ModelEntry>

" Remove the following lines: <CMS_ENTRY, <CMS_MODEL_SPEC_IDX, <U_14 and <IS_DLC

What can you customize from here? Really nothing... the values here may not be used, or if they are, they may not be used in all places (some of these values have "twins" in the Slot entry that will be discussed later).

So, after finishing this step, the xml in our example looks like this.

Step 3.3: the ModelPosEntry

This time, open the file CharacterSelectPosition.csp.xml.And like before, search for the entry of the character your one is based. Copy paste from<ModelPosEntry> to </ModelPosEntry>.

Remove <CMS_ENTRY and <CMS_MODEL_SPEC_IDX. Now you may be wondering what is all this rubbish... well this file seems to control the position in which the character is when you select it. But also, apparently, it controls the position of the character in the fight. Chance are that some of these values are 3d coordinates.


But anyway, just keep the values there (if you copy pasted the values of a different characters, you will notice odd things, unless the other character happens to have similar characteristics).


So after finishing this step, the xml of our example looks so far like this.

Step 3.4: the ModelRpdEntry

And now, open the file ResultPositionData.rpd.xml. Like before, search for the charcter your one is based. And copy from <ModelRpdEntry> to </ModelRpdEntry>.Like, it was done in the <ModelEntry> of step 3.2, remove the id="..." thing, leaving that line like "<ModelRpdEntry>"

Remove the lines <CMS_ENTRT and <CMS_MODEL_SPEC_IDX.

You may have noticed the <NAME field. Well, don't bother changing that. It seems that the game totally ignores that info, so just leave it like it was. As for the rest of values, they are undocumented. The ModelRpdEntry controls the position of the character at the end of the battle. And apparently, it may also control their phrases. If you saw the video of "Overflow of Hildas", at the end of the video you could see Freya in a weird camera mode and not saying her line. That was caused, because back then, the rpd data wasn't being patched.


So, mmm, until these values are documented, just leave everything from the base character.


After finishing this step, the xml of our example looks so far like this.

Step 3.5: the Slot data.

Yeah, I know what you are thinking. That there are must be infinite values from infinite files to copy. But this is the last one. So now open the file slots_data.slf.xml.

This file is actually a compendium of data that is stored inside the .exe (what I call "pre-baked") Some of the data is directly related with information associated to the slot, and other info is unrelated but I put everything together to avoid having infinite files. Don't worry about that, all that sh*t is handled by sssspatcher.


Just like before, search for the data of the chracters yours is based. And copy from <Slot> to </Slot>

Remove <CMS_ENTRY and <CMS_MODEL_SPEC_IDX.


So, what can you modify from here? You could change the "SIGN_NAME_ID", for example (where "sign name" refers for example to Aries, Taurus, Pegasus, Megrez, Chrisaor, etc), but currently, you can only specify a hexadecimal value of another character. Same goes for the AVATAR_ID, and ROBES_NAMES_ID. In the future, I have plans so that you can put your own data there, but atm all you can do is use values of other characters. (Please, make sure you use a valid values in those, if you get out of range you could cause a crash). If you don't need to change the names, leave it like that.


The value of AVATAR_ID is only important if your character doesn't use a custom avatar (see Step 5).


And now an interesting field, the CATEGORIES. This controls how your character may be identified by other characters. The information may or may not be used at all places, but it is worh filling anyway. A character can belong to multiple categories, just put them separated by ",". Valid categories are all that you find in that file.You can't make your own category

or anything like that. The order doesn't matter at all.


When in doubt, consult the values of original characters. For example, notice how gold saints without gold armor are not in GOLD_ARMOR category. Or notice how gold saint spectres are in category "HADES_AND_SERVANTS", where Hades, Thanatos, Hypnos and the 3 judges are too.


In our example, we will add the GEMINI_EVIL_SAGA_SAINT category to the original values of God Gold Gemini. You can put any combination. If you want to say that your character is an Athena and and Hades, then so be it. As far as you use valid strings, the program will be fine, and sssspatcher will patch the lists that the game keeps for this information.


So, after finishing this step, our xml looks like this.


And we are actually finished. If we don't need any other additional files, the xml would be finished by now and you could move to step 5. Otherwise, read step 4.

Step 4: Adding additional files (optional)

Firstly, a philosophy lesson. The philosofy of new characters mod is to ADD, not REPLACE.

Technically you could use the feature of ssz files that will be discused in this step, to replace existing files. But you shouldn't do it unless you have a valid reason, which in most case it won't be valid So, just stick to add new files, when possible.

Let's say we want to make our Evil Saga God armor mod to have different visual effects than the original Saga God armor. This is not the case of my Evil Saga mod, but for the sake of this example, let's assume it is the case.

We could use the guide of netus01to change color effects of VfxSGAEfct.emb. But following our philosofy of ADD, not REPLACE, we would save the changes in a file that doesn't exist in vanilla game. For example VfxMyEvilSagaEfct.emb. Then, in the folder where we have sszmod.xml, the emo, etc, we create a folder called resource.Then inside the resource folder, we create a folder called vfx. And inside vfx, we create a folder called CHARA (basically we reconstruct the game folder structure), and inside that, we put our VfxMyEvilSagaEfct.emb.

Now we must tell the game our character uses that file. Remember the beautiful ModelSpec

that we added in step 3.1? So now, we change the <VFX line to


<VFX value="VfxMyEvilSagaEfct.emb" /> You could follow same logic to change other files, like the .tdb file (it contains the text the character says in battle), etc. You can also find an example in my Pandora mod: my pandora needs a different fce file than Hilda. But as we don't want to overwrite Hilda one, I used this feature of .ssz mod to copy additional files, and I specified the .fce file in the FCE of <ModelSpec>

Basically: anything you have in the resource folder (if it exists) of your .ssz mod, the installer will blindly copy it to the resource folder of the game (except for empty folders). You could technically put the full game data in there, and the installer would copy it... but don't that

Step 5: adding an avatar image (optional)

If your mod needs a custom avatar, you can include one here. Note that if you just want your character to have one of the vanilla avatars, you shouldn't use this step. Instead just set the AVATAR_ID in the Slot entry.

Including an avatar is easy, just put the .dds file with the name "avatar.dds" in the same folder where you have the .emo, .emb, etc. SS Mods Installer / sssspatcher don't check the format of the image, but remember that the game uses 256x256 files, in DX5 without mip maps, file size should be 65664 bytes.  

Step 6: adding a preview image (optional)

You can add a preview image to your mod, by including a file called "preview.png" in your package. This is totally optional. SS Mods Installer will usually display the image with an aspect ratio of 1:2, this is, the height is the double of the width. You should try to keep your image with that ratio, when possible. (for example, 419x838, 450x900, 540x1080, etc). It is not a strict requirement because the installer will stretch the image anyway, but the closer you are to the 1:2 aspect ratio, the less weird the image will look on both, the preview window and in the mods list preview. 

Step 7: creating the zip and renaming it to .ssz.

This step will use WinRAR as example, but it is similar in other programs. Select all your files in the file explorer: the .emo, the .emb, the .emm, the .2ry, sszmod.xml, and, if they exist, the resource folder and the preview.png file, click right button and select "Add to archive..." (not add to "XXX.rar" or "XXX.7z) In the window that it pops up, select .zip as format (not rar, .7z or anything else). Use the name you want for the file, but make sure to put the .ssz

extension instead of .zip.


And that's it. your mod is ready to deploy. Just make sure to test it before uploading it, you may have made some silly mistake in the way.


(Please, don't compress the outer folder where your files are, instead you must select all the files like I said in this step, I can foresee that this will be a very tipical mistake).