PL2/OPL2 model modding

This guide will teach you how to make 3d model mods for PL2/OPL2, with Blender. Users of other 3d packages (except Metasequoia) right now have to use Blender as a bridge: import the models in Blender and export it to a format which supports all that is needed and import it in their 3d modeller and do the opposite for exporting. Blender is completely free, lightweight and to do this you'll only need to know the basic UI of Blender. If you would like to make an importer/exporter for other 3d packages, contact me. 3d model mods in PL2/OPL2 are archives which contain 3d model file(s) and one configuration file. The 3d model files are *.tmb models, which is a simple binary format. The configuration file is a txt file, with no extension, named attribute. PL2 is a japanese game and the text must be in shift-jis, not ascii or unicode. OPL2 might support unicode configuration files in the future. This is a good shift-jis text editor: link We'll learn how to use that editor too when we'll learn how to create such attribute files. The current 3d modellers which can export to TMB are Metasequoia, Blender 2.4 and Blender 2.6. Blender scripts can be found here: 2.4 version: link 2.6 version: link Metasequoia tools can be found here: link TMB format specs can be found here: link Support for other 3d formats inside 3d model mod archives might be added in the future to OPL2. The configuration file structure can be found here: link Different model addon types use different values inside the configuration files. To get all the files to a *.pl2 archive, you'll need the free PL2 unpacker/repacker tool, found here: link Simply drag a folder or a PL2 archive to the exe. This guide is meant for Blender 2.6, though the process is pretty similar for Blender 2.4. OPL2Viewer is a media viewer supporting PL2/OPL2's formats. You can use it to preview your exported TMBs, as well as extract PL2 archives. The viewer can be downloaded from here: link

PL2 Blender addons are just like any other Blender addon. You can copy them to Blender's addons folder or install them through the UI. In any case they must be enabled through the User Preferences window.

PL2 TMB models can be separated into two groups: containing skeleton (Armature) and static models. Usually room mods all are static models, but not necessarily. All character and clothing models have skeletons. In fact they all have the same skeleton (though different skeletons for male and female models).

This might seem weird, as some games have simpler skeletons, for say, clothing and that skeleton kind of gets attached to the body skeleton in-game. But once you think about it the way PL2/OPL2 does it is actually simpler: since the body model and all clothing/accessory

types use the same skeleton, you can have them all attached to single Armature inside Blender and just export each individually by selecting it and the only Armature. This allows us to very easily preview a whole character mod with its body and clothing/accessories together. And with all the bones available to any kind of mod, like upper and lower clothing, modders aren't limited in size or shape of their clothing, etc. Note that TMB is a very simple format, no skeleton hierarchy is stored. So always make sure to keep the original .blend file if you plan to modify it later. Now you're probably wondering: well if no skeleton hierarchy is stored, original TMBs are pretty useless, as posing them for animating will be almost impossible, right? No. We took care of that. As the original PL2 game only uses two skeletons for all the models, we thought we'd hardcode a proper skeleton in the scripts and allow to use them by clicking on a single checkbutton in the importer/exporter, Hardcoded Armature. This is, after all, what the default japanese animation editor for PL2 does. So you can easily modify, pose and animate existing TMB models. Plus, you'll really want to use this option, as the original TMBs were made in a 3d modeller that didn't really have bone angles, so the bones look pretty weird, facing random directions:

And here's the Hardcoded skeleton:

We are going to start by importing existing models to Blender and animating them by importing

an existing animation, to check if everything works fine and get used to the tools. Unless you're planning to make completely custom skeleton model which will use custom animations (you'll need to write scripts for that too), you should import an existing TMB, delete everything except the skeleton and use it. The importer has quite a few options:

Each checkbutton has a description you can read by hovering the mouse cursor over them. Each time you import a new TMB, a new skeleton is created, but you can import few models, delete all skeletons except one and make all models use it instead, by selecting them and then the Armature and pressing Alt+P With Empty Groups. We'll do that now:

Now lets import a TSB animation to check that everything is right.

TSB files in the original game can be found inside the archive sc_res.pl2, in the add-ons folder.

Right, everything seems fine. If you got an error, make sure you had the Armature selected before importing. And also make sure you are using correct version of Blender. Even subversions (2.6.x) of Blender often break old code. Now we are going to export the models from Blender to TMB and check them in OPL2Viewer. Exporter scripts work on currently selected objects only. We can preview our exported models with OPL2Viewer.

Great. We just passed a TMB model through Blender. Next we can create our own by using an Armature from another TMB model. The original female Armature has 195 bones. That's a lot. But remember that it is used by all kind of model mods, from bodies to hair and clothing. Easiest way to work is to hide the unused bones, for example hide all clothing and hair bones for body model. There are no bone groups which will allow you to guess which bones you won't need, but it's pretty easy to guess just by looking at them, and similar bones always have a common parent. Here are images of the standard female Armature and it again with hair and clothing bones hidden:

Not so frustrating anymore, huh?

Note that TMB only supports triangles, not quads/ngons. So you need to triangulate your meshes before export (Ctr+T). You can always undo that after exporting (Ctr+Z). OK, lets say now we have created few models and want to make a PL2 model mod we can put in the game's folder and have it appear in-game. To do that, we need to write an attribute configuration file, put it in the folder with the TMB models and pass the folder to the commandline archive creator exe. First of all, how many types of addons are there? There's the ARCHIVE type, which contains media files (not only models) which are made accessible to the PL2 scripts. The rest are model addons. They are COORDINATE, BG, ARM, COSTUME, EYE, FACE, HAIR, HEAD, NECK, SHOES, SOCKS, UNDER. They type defines where the models appear in-game in the Clothing Selection screen and how they are stored and accessed by PL2 scripts. COORDINATE addon specifies a whole character model, body, clothing and accessories. BG is for room addons. Rest is self-explanatory. This page explains each addon type in detail: link Start up our text editor, JWPCE. By default the editor writes in Kanji. You can switch to ASCII or JASCII (aka shift-jis) anytime you want.

In shift-jis (JASCII) mode you can write latin characters by typing as usual. But note that the latin characters in JASCII are not the same as in ASCII! JASCII should only be used for certain values (for example names that appear in-game). When done, click Save As Shift-JIS. As there are many addon types and showing an example for each here would be too much, and

as the page we linked to previously already has that, we're only going to show an example BODY addon attribute file. BODY addons just contain the body, no eyes, hair and underwear.
VERSION=100 TYPE=BODY SEX=FEMALE NAME=imo_eye_04 CAPTION_0= CAPTION_1= CAPTION_2= OBJNAME_0=imo_eye_04 FILE_0=imo_eye_04.tmb ICON_0=imo_eye_04.psd

As you see a configuration file contains lines with key and value pairs, separated with a = sign. Some keys are not really used by the game, they are just there for the modder. In these case they are VERSION, SEX, CAPTION_2 and OBJNAME_0 NAME is important as it'll decide the order in which your addon will appear in Clothing Selection Screen. CAPTION_0 and CAPTION_1 are the name and description of the addon in the Clothing Selection Screen respectively. They must be in JASCII. FILE_X is the TMB file used. Note that the TMB file doesn't have to be in the same archive, mods can share models. ICON_0 is the PSD image. When you have the models and config file in the folder, you'll also need an icon file which will appear in the Clothing Selection Screen. It should be in Photoshop's PSD format. You can also use the free GIMP program to create a PSD image. It should have two layers: first one will be shown when the addon is not unlocked in-game, the other one when it is. Resolution should be 40x40. Colors in RGB(A).

When that's in the folder as well, drag and drop the folder to the exe packer and it should generate a *.pl2 archive in the same folder. Move that to the game's add-ons folder and you're ready.

You can delete the folder now as you can always unpack the *.pl2 archive to a folder with the same exe or OPL2Viewer.

If for some reason it doesn't appear in the Clothing Selection Screen, make sure you've specified the correct addon type in the attribute file and that your PSD image has 2 layers, not 1. One more thing which isn't that obvious: if you have a model which contains the hair, eyes and maybe even underwear and clothes and you're lazy to separate them and make TMBs for each, there is a way to have one TMB and tell the game to hide all the current models (body, eyes, hair, etc) and use that instead. You're looking for the COORDINATE type addon.
VERSION=100 TYPE=COORDINATE SEX=FEMALE NAME=myname CAPTION_0= CAPTION_1=My description ICON_0=my_icon.psd COORD_00=my_model.tmb COORD_01=nil COORD_02=nil COORD_03=nil COORD_04=nil COORD_05=nil COORD_06=nil COORD_07=nil COORD_08=nil COORD_09=nil COORD_10=nil COORD_11=nil COORD_12=nil

nil means remove any model in this slot. That's it. OPL2 is an open source game, if you have a suggestion for better model modding design, let us know. Any new feature for OPL2 won't work with the original closed-source PL2 game though.

Animations are a lot easier to make. You select an Armature in Blender and run the script. If the Armature is the hardcoded one, click on the Hardcoded Armature button in the importer, same for the exporter. The importer creates a new Action for the Armature, the exporter only exports the current (active) Action. Now to make animations appear in-game, you need to modify the game scripts, which is too much to put here, so getting animations from Blender to PL2/OPL2 was put in its own tutorial. There is a mod for OPL2 which allows to change the animations of characters in-game at any time, without having to modify the game's scripts. Check that out too.