Importing character models

A few words from the masters

This is not really a tutorial, more like an overview of the tools, notions and operations, some of it technical and/or vague. Someone special ought to do something special about it, soon. Iritscen, hapécat-in-chief Why me? Why ME?? WHY ME??? geyser, syndicate accessory

Modding tools

OniSplit

The program that we use to get models into Oni (and out of it as well). It is a command line tool. There are GUI extensions for OniSplit that cover its most basic functions, but modders typically have to call it from the command line to take full advantage of it.

3D programs

XSI

A powerful free tool available on PC only is (formerly "XSI") Mod Tool. It has very detailed documentation, and is very versatile, whether working with characters or levels. More or less free equivalents thereof probably exist on the Mac platform. The latest versions of the Mod Tool can no longer export OBJ, or

Blender

Blender is mostly OK, but it is not as flexible as ModTool when it comes to manipulating objects in different frames of reference. AFAIK, there is not much control over local translation and rotation (i.e., relative to the parent), as opposed to global translation and rotation (in world space). Also, IIRC, in Blender objects have "centers", but those centers are points, with no information on rotation. This means that the center does not really define a local frame of reference at all. The general workaround is to use skeletons, rather than a bunch or meshes parented to each other. I am using only XSI when working with characters.

Blender rocks when it comes to lightmapping levels, though. XSI is closed source and can only lightmap one mesh at a time with one lightmap texture per mesh. Blender is more flexible because of its free-for-all scripting API, and a nice touch is that it supports radiosity (i.e., emissive materials - and that's exactly how Oni's lighting was done initially, see OBLS).

File converters

Autodesk FBX

Check out Autodesk FBX Tools (primarily the FBX converter) if your tool can reliably import/export FBX but has trouble with COLLADA.

3D Exploration

A convenient little program, which used to be free (nagware) before turning into Deep Exploration. The free version is still available, and is very useful, although it does not support COLLADA.

MeshLab, Blender etc

MeshLab is a recent converter and editor, apparently more focused on 3D scanning and printing. Support a lot of formats including COLLADA, but not flawlessly. Blender has a rather complete set of import/export scripts, and in many cases it will do the job as a last resort.

Basic importing and exporting

Exporting from Oni to COLLADA

Onisplit allows you to export .dae files from both TRBS and ONCC (with or without a -noanim tag in the case of ONCC). Examples:

• after having globalized all the characters, go to the Oni\edition\GameDataFolder\level0_Final folder
• enter ..\..\install\OniSplit.exe -extract:dae collada -noanim ONCCmuro_generic.oni

or ..\..\install\OniSplit.exe -extract:dae collada ONCCgriffin_generic.oni

or ..\..\install\OniSplit.exe -extract:dae collada TRBSkonoko_body_high.oni

Of course the relative paths used here are only an example. Mac users should adapt command-line syntax as necessary.

This will create the files ONCCmuro_generic.dae, ONCCgriffin_generic.dae, and TRBSkonoko_generic.dae in the folder Oni\edition\GameDataFolder\level0_Final\collada. The difference between ONCCgriffin_generic.dae and ONCCmuro_generic.dae is that Griffin will appear with an idle pose, whereas Muro will be in the default animation state (standing upright, arms extended sideways at about 70°). As for TRBSkonoko_body_high.oni.dae, she will be in her default animation state and will have no materials/textures set up. See the notes below for explanations.

The textures are listed in the TRMA file, which is only visible from the ONCC, not the TRBS. If you want to use the textures while editing the model, extract the .dae from an ONCC, not from a TRBS.

Importing from COLLADA into Oni

When importing characters, the simplest is to generate a whole body set (TRBS) from one .dae file. For the above characters it goes as follows:

• after the example above, go to the Oni\edition\GameDataFolder\level0_Final folder
• enter ..\..\install\OniSplit.exe -create:trbs collada collada\ONCCmuro_generic.dae

or ..\..\install\OniSplit.exe -create:trbs collada collada\ONCCgriffin_generic.dae

or ..\..\install\OniSplit.exe -create:trbs collada collada\TRBSkonoko_body_high.dae

This will create TRBSmuro_generic.oni, TRBSgriffin_generic.oni, and TRBSkonoko_body_high.oni in the folder Oni\edition\GameDataFolder\level0_Final\collada.

You can rename these TRBS appropriately so that they are used by either some of the old ONCC or some new, cloned ones. Finally, rebuild the level to test the model.

Because they were imported from a single .dae file, each of these TRBS will contain 5 identical levels-of-detail (LOD). You can specify a different .dae for every LOD by importing from XML (as detailed elsewhere).

Textures are currently ignored upon creating the TRBS (however, the TRBS will of course retain the changes you may have made to the UV coordinates). Possibly future versions of OniSplit will automatically generate a TRMA if the .dae file has textures.

An ONCC contains much more information than links to TRBS and TRMA and thus can not be generated automatically ATM. The easiest way to try out an imported character in Oni is to rename the imported TRBS so that it replaces an existing one. Eventually, you can clone an ONCC (in XML) and make it link to the new TRBS.

The authoring of the new ONCC can be done either in binary (with a hex editor), with OUP, or in XML (see, e.g., HERE).

Poses

Oni' s default orientation

The primary axis of a body part, in its own frame of reference, is X. When you move down an arm or leg, or up the spine, you are moving along the positive X direction of every body part. When all the bones are aligned with their parents, you get something like this:

14-o-13-o-12-o-11-o 3-o-2-o-1-o       ^ z
                  |           |       ^
           :)10-o-9-o-8-o-7-o-0  < < <^< < <
                  |           |   x   ^
18-o-17-o-16-o-15-o 6-o-5-o-4-o       ^

This is a conventional reference used in all of Oni. For any animation of any character in Oni, the rotations of the body parts are calculated with respect to a default pose such as this one. This allows the characters to share animations, even if their "skeletons" (TRTA) have slightly different proportions.

In the default pose, the XYZ axes of all the bones are oriented the same way. Thus, on the default pose, you can directly see the translations of every body part with respect to its parent, as stored in the "translation array" TRTA. For example, in Konoko's case, the "mid" section (part 7), is translated by 1.67 WU along X (i.e., 16.7 cm towards the top of the spine), and by 0.25 along Y (i.e., 2.5 cm towards the front of the spine). Remember that this translation is in the "local" frame of reference of the pelvis, i.e., with respect to the origin of the pelvis and to its local XYZ axes (which are generally different from the world axes). Basically, the local X of the pelvis always points up the spine, the local Y points forward, the local Z points left), and the same goes for "mid", "chest", "neck" and "head".

-noanim pose

A less awkward default pose than the one above is exported by OniSplit with the -noanim tag:

• after having globalized all the characters, go to the Oni\edition\GameDataFolder\level0_Final folder
• enter ..\..\install\OniSplit.exe -extract:dae collada -noanim ONCCkonoko_generic.oni

or ..\..\install\OniSplit.exe -extract:dae collada TRBSkonoko_body_high.oni

The result will look something the picture on the right, but not quite, because Kuchum ripped the model on his own.

In the "noanim" pose extracted by OniSplit as of 20:14, 3 October 2010 (UTC), all rotations are 0 except:

(0,90,90) for the pelvis,

(0,180,0) for both thighs,

(40,60,140) for the left shoulder

(-40,-60,140) for the right shoulder

The placement of the pelvis is adjusted for Konoko, so that the soles of her feet are at Y=0. For male characters the feet will be at Y<0.

A very close alternative to this pose is (0,70,180) for the left shoulder and (0,-70,180) for the right shoulder. Try setting it in XSI.

The intuitive (0,0,180) rotation doesn't work as well with the arms as with the legs. The orientation is correct, but because of the narrow spacing of the shoulder joints the arms end up inside the body.

Idle pose

If you use -extract:dae TargetFolder ONCCkonoko_generic.oni (with ONCC rather than the TRBS , and without -noanim), OniSplit will look up the idle animation from the ONCC's TRAC. Rotations (relative to the reference layout of the joints) are applied to the body parts.

Keep in mind that this idle pose exported by OniSplit is just an arbitrary natural-looking pose, as opposed to the default orientation or the "standard" -noanim pose. The first frame of an idle animation is certainly not a standard pose for you to match when importing a new model (unless you are swapping body parts between Oni characters that use the same idle pose, in which case you don't have to match anything anyway).

Any pose

When exporting from ONCC, you can use the -anim tag to specify any TRAM, as long as it can be found in the character's TRAC (and as long as it's not an overlay animation). Or, you can just start from the -noanim or idle pose, and tweak the rotations to match any pose you like.

Things to do

Bastardizing

This is possibly the easiest kind of modding, that doesn't require texturing skills or even, in most cases, attentive handling of poses and joints. The idea is to:

1. take two Oni characters (for simplicity, two characters who use the same skeleton: e.g., the Konokos from CHAPTER 13 . PHOENIX RISING and CHAPTER 10 . CAT AND MOUSE)
2. load both of them simultaneously into Mod Tool or Blender. In Mod Tool, just drag-and-drop the .dae files, but "Select none" (Ctrl+Shift+A) before you do, to make sure that you drop both into "Scene_Root")
3. reparent some body parts (rename if needed) and trim the rest (since the orientations and joint offsets match, you don't need to rotate/move anything)
4. export, adapt the TRMA if needed, rebuild the level and play

This allows one to recombine Oni's characters into "new" ones very easily. Probably the easiest thing is to add sunglasses to any Konoko model ^_^ (or Konoko's head to any female character)

Cel-shading

An effect similar to cel-shading can be obtained by enclosing the mesh in a shell painted in black and facing inwards.

As of 0.9.8, OniSplit can perform this operation with every body part, in an automatic way, with one control parameter (a sorta "margin", or effective thickness of the "shell").

The syntax is as follows:

FolderWhereOniSplitIs\OniSplit.exe -create:trbs TargetFolderForCreatedTRBS -cel FolderWhereTheModelIs\name_of_the_model.dae

or FolderWhereOniSplitIs\OniSplit.exe -create:trbs TargetFolderForCreatedTRBS -cel:0.1 FolderWhereTheModelIs\name_of_the_model.dae

The -cel option enables the generation of the shell. The optional parameter (default 0.07) defines the thickness of the shell.

Note that the shells may not be good-looking in every situation without some further tweaking. Rextract the TRBS or ONCC, tweak the shell, and reimport normally (without -cel this time).

Some examples of automatically generated shells (not tweaked in any way) can be seen here: http://geyser.oni2.net/edition/celshading

New models

Matching body part centers

There is actually no such thing as a "standard" pose for 3D characters: the width of the stance, the stiffness of the spine, the angle at which the arms extend from the body - all that varies a lot between models. Therefore the model of your dreams (Gally, Master Chief, Eva-01, whatever) will typically come with a somewhat "random" pose, which has nothing to do with either Oni's default pose, or even with the -noanim "standard" exported by OniSplit. Another problem is that, if you roundtripped your character through OBJ (which doesn't support relative placement and rotation), then all the bones are essentially defined in world space, i.e., their centers are at the world's origin, and their axes are aligned with the world axes.

What can we do about this? Here's what:

1. First, make sure that the model that you want to import into Oni is split into 19 separate body parts, and that they overlap nicely even under extreme rotations (see below). The "extremes" are something that you can fix later, but you really need the character to be split into 19 body parts. If some of those parts are missing (e.g., Barabas has no visible shoulder parts), you will still need placeholder meshes (see Barabas as an example). So, get all those meshes ready, alongside each other, at the root of the scene (no hierarchy needed right now).
2. Now, load an Oni character exported with OniSplit into the same scene. This character will be your posing figure, so make sure it is similar (in height and "width") to the one that you want to import (i.e., don't use Konoko to match Master Chief, and don't use Barabas to match Gally). Tweak the rotations of the Oni character until it overlaps with the "random" pose of the new character.
3. Sometimes you can't make everything overlap just with rotations, and in that case you have to actually translate bones with respect to their parents. By doing this you are actually modifying the skeleton of the Oni character, bringing it closer to the proportions of the new character. If this is the case, and if you want the new character to use Oni's animations, you will have to make sure that the length of the legs stays roughly the same. If the legs of the new character have about the same length as those of an Oni character (measured between the hip joint and the sole of the feet, or between the pelvis center and the sole of the feet), then the animations may look a bit different, but at least during basic stances and movements the feet will stay roughly in contact with the ground, not above or below.
4. Now, you can inspect the Oni character, which you have posed in a way that is consistent with the "random" arrangement of the new body parts. Try selecting the body parts of the "posing" Oni character, one at a time, and inspect the values of the translation and rotation of the mesh with respect to its parent (i.e., "Local"), in the "Transform" panel (far right). Try switching to "Center" in the "Select" panel (top right corner), and inspect not only the values in the "Transform" panel, but also the color-coded local axes, which can be seen sticking out of the center of every selected mesh, in the viewport. Try to interpret all this, in terms of the "translation array" (TRTA) and Oni's conventional neutral pose (see above).
5. The next (and last) step is to ensure that every part of the new character is parented correctly (the thighs to the pelvis, the calves to the thighs, etc), and that the center of every new body part is placed in the same way as the center of the corresponding body part of the "posed" Oni character. To see the centers of all body parts of the Oni character, all at once, just select all of its meshes, and either select "Center" in the "Select" panel, top right, or check "Centers" in the drop-down "eye" menu, in the viewport.
6. Basically, the only thing that you will be doing is: reparenting the bodyparts of the new character to each other (by drag-and-dropping them in the "Explorer/Scene_Root" viewport), and matching the translations and rotations of their respective centers to the centers of their counterparts in the posing mesh, which we know to be correct. Therefore, make sure that "Center" is selected the whole time: we are not moving the meshes themselves, only redefining their relation to each other and their local frames of reference. Some of the matching can be done automatically, but it won't always work, so be ready to copy some values by hand, from one mesh to the other.
7. The basic order in which you proceed is this.
   • Select the new pelvis. It already overlaps with the "posing" pelvis, and it needs no parent. The only thing that's wrong with it is the position and rotation of its center. So, what you do is, you select the new pelvis (or rather its "Center"), and then in the drop-down Transform menu, click "Match all transforms", and immediately pick the pelvis of the posing Oni character (in "Explorer"). This should make the center of the new pelvis collapse onto the center of the posing pelvis, which is where we want it to be.
   • Actually it seems that, in the latest version of ModTool, the automating matching of transformations is done in global coordinates, not in the local frame of reference. (IIRC, in previous versions of XSI, it was possible to match transforms in the "Local" sense.) This means that the rotation will probably match correctly, but the translations will typically be off, so you may have to copy them manually.
   • Basically, after you "Match all transforms", check the orientation of the new pelvis's center (the triplet of Euler angles in the "Transform" panel, and the color-coded axes sticking out of the center, in the viewport). Make sure that the axes look the same as for the posing pelvis. If the Euler angles look different but the axes look OK, then you are probably looking at equivalent Euler angles.
   • Now, select the left thigh (which is not parented to the new pelvis yet). Drag and drop it into the new pelvis in the "Explorer" viewport (i.e., reparent it). Normally, no meshes should move when you do this. But if you move or rotate the center of the new pelvis now, the new left thigh will also move and rotate, because it is already relative to the pelvis. This is why you need to do the pelvis first.
   • There is still one thing wrong with the left thigh, and that is the placement and rotation of its center - it is still, e.g., at the world's origin (in this pose), and we want it to be where the center of the posing left thigh is. So, we select the new left thigh's center, then choose "Match all transforms" in the Transform drop-down, and pick the "posing" left thigh in "Explorer". Same as above, check the rotation (Euler angles and local axes), and fix the translation manually if needed. Now our new left thigh should also be OK.
   • All the other body parts are done the same way. Be sure to proceed from the root of the hierarchy to the extremities, and check your results from time to time. Make sure you don't match the posing body parts to the new body parts instead of the other way round. In other words, look carefully at the first steps detailed above, and make sure that you know what you're doing.

All of the above is done in ModTool. I have no idea about how you'd do this in Blender, never tried. AFAIK, not only is Blender incapable of matching transforms in the local sense, but manual setting of transforms can be done in the global sense only. This means that you would probably need to reduce the new model to Oni's neutral pose, or use a skeleton.

Making joints look nice

Apart from the consideration regarding the pose (see above), you should be aware of the specific nature of Oni's body parts. Have a good look at an Oni model before you import a new one. Especially look at the generous overlaps between the body parts.

If you're importing a skinned character, you may have to completely remodel the following regions: elbows, knees, waist, diaphragm. E.g., it's not enough to just cut the leg at the knee. Both the thigh part and the calf part should wrap around the knee joint, and intersect with the other mesh over about 1 world unit (10 cm). Same for the elbow.

The bulk of the shoulder parts (except for Barabas, who doesn't have any) is supposed to bridge the gap between the chest and the arms for the more "extreme" kind of animations. Oni's characters mostly use capsule-shaped primitives for shoulders, so if your new model doesn't have anything that you can use, you can always borrow shoulder parts from an Oni thug, or whoever.

As for the spine, large overlaps (and clever overall decomposition into pelvis/mid/chest) are needed to allow for the extreme bending of the spine (think Backbreaker). Feet and fists can be resolved rather easily (you just extrude them a bit towards the calf/wrist), but you should also mind such things as two-handed aiming overlays.

Working example

For the sake of this sorta tutorial, we shall pretend three things:

• Berserker Gally from GUNNM Martian Memory (a PSX game) is, like, the coolest model ever (see left);
• we want to make into, like, the coolest Oni character mod ever made, or die trying;
• as the provider of the (ripped) model, I am not your bitch housemaid (meaning that, although I could rip an OniSplit-ready DAE or even an Oni-ready TRBS, I will not);
• as the writer of the tutorial, I am not your maid either (maybe I could explain it better, with screenshots at every step, but then you wouldn't suffer, and you wouldn't learn half as well).

We shall proceed in steps. The ripped model is provided as-is HERE (well, not really as-is; I roundtripped it through 3D Exploration)

1. Start a "File/New scene" in XSI, and open this thing with "File/Import/OBJ file". In an "Explorer" window you shall see that there are 15 "bone-something" objects, and 19 "part-something" objects.
2. Don't go thinking that the 19 "parts" are the ones you need for Oni, because they're not. They're just meshes. As you will soon find out,
   • there are no shoulder parts,
   • parts 7 to 11 part all belong to the head,
   • part 18 is pelvis, mid and chest combined, and
   • the open hands are in a separate OBJ file.
3. There is a bunch of basic things that you want to do before actually adapting this character for Oni
   1. The first thing you want to do is combine the head meshes into one. Just comment out the "g" tags for parts 8 through 11, in the OBJ file, and you should get THIS. Reimport it into a new scene, and see what changed.
   2. Don't mind the "bone" objects for now. I just happened to include them in the rip, but I'm not sure why.
   3. Sooner or later you'll want to select all the objects (or just "Select all" and deselect the light and camera) and rotate them by -90° along X, so that Gally is upright.
4. Now you want to split the body mesh (part 18) into three parts and to add some placeholder meshes for the shoulders.
   1. The shoulders you can get from Barabas. Drop his DAE into the "Scene_Root", reparent the shoulders to "Scene_Root", delete the rest of Barabas, and then scale/move the shoulders around until they fit inside Gally's chest. Try to keep them symmetric.
   2. As for the splitting, here is what you do. You duplicate part 18, twice, then hide all the duplicates but one, delete faraway polys, move the adjacent vertices around a bit, and then close the mesh with new polygons (N for making a new triangle, then Esc and Ctrl+Shift+A before creating a new one, to avoid making a quad). While you're editing the body, you may notice that some quads were apparently triangulated even though they are not perfectly flat, and the triangulation is not done the same way on both sides of the body. You can fix it now (Dissolve, Subdivide, re-Dissolve), or you can save it for later.
   3. When you're done, you can add the hand meshes from the extra OBJ file. To place them correctly, you can use the coordinates of the tips of "bone_4" and "bone_7" (aha! I knew they'd come in handy)
   4. When you're done with that too, you want to get her ready for a "matching session" with an Oni character such as Konoko. Select all objects, then "Freeze all transforms" (from the drop-down menu of the "Transform" panel), then scale the whole bunch by 2 along all axes (don't ask, just do it), and "Freeze all transforms" again.
   5. Now every object (including Barabas's shoulders) has unit scaling, 0 rotation and 0 translation. Since all the meshes are parented to the scene root, "0 rotation and 0 translation" means that all their centers are at the world's origin, and the axes of the centers are aligned with the world axes (you can check that by switching to "Center" in the "Select" panel, or by enabling the drawing of Centers in the "eye" drop-down menu of any viewport). If you haven't done it already, you can rename the "part-something" meshes to the standard names used by OniSplit.
5. Now is a good time to save your work, either as an XSI scene or model, or as Collada. I prefer Collada for some reason, but you must be careful to export only the selection (you don't want the "Scene_Root" to be exported, or the camera, or the light). Just select all the objects (including the "bone-somethings", because they might come in handy again), then "File/Crosswalk/Export", set the exported type to COLLADA, the filename to something sensible, and in the Settings, make sure that "Selection Only" and "Keep Referenced Paths Relative" are ON, and that "Verbose" and "XSI Extra" are OFF. You should get something like THIS (tweaked a bit in a text editor, to remove the link to TXMPTextures_babamid, and to make the hands and the rest of Gally use the same material GLB).
6. Now there's only a few things left to do. Our last step will be the "matching" of Gally's body parts to those of a modified Konoko. But before that, there are some preliminaries.
   1. Start a new scene in XSI, and drag-drop the Gally you just saved into it. Delete the fists if you want to, and name everything according to OniSplit's standard, if you haven't already.
   2. Use OniSplit to "extract" ONCCkonoko_generic to .dae, with the -noanim tag, and drag-and-drop her into the same scene.
      • If you named Gally's meshes correctly, then Konoko's meshes will be disambiguated with a "2". This is not a problem.
      • Note how the height of Konoko's pelvis (and hip joints) is consistent with Gally's. That's what the factor 2 was for.
      • Also note that Gally's upper body is rather small in proportion to her legs, and that her calves are slightly longer.
   3. Rotate Konoko's arms and shoulders to match Gally's pose. Try (0, +-65, 180) for shoulders and (0, +-65, 0) for arms.
   4. Now translate Konoko's body parts (not the centers) so that their centers match the supposed centers of Gally's.
      • Work from the pelvis down the tree, because if you move, e.g., "mid", all the upper body will mode too. So, do "mid" first, and don't touch it afterward.
      • Use Gally's "skeleton" to pinpoint the supposed centers of her meshes. To see Konoko's centers while you move the objects, use the viewport's "eye" settings.
      • Shoulders, mid and chest can be tricky because the original Gally has no shoulders or mid, and chest has translation 0, unlike in Oni (probably the spine is meant only to twist, not to bend). Just try to place all those bones in proportion with the head-neck distance and approximate shoulder width (which is a bit narrower than Konoko's. Maybe it's better to use Shinatama Too instead of Konoko, here. In any case, don't be afraid to translate Konoko's body parts away from the original locations, as long as this "compact Konoko" gets close to Gally's proportions.
7. When you're happy with the overlap, you are ready to match Gally's body parts to Konoko's; both in terms of hierarchy (TRIA) and in terms of relative placement (TRTA).
   • Switch to "Center" in the "Select" panel, select "pelvis" (Gally's), then click "Match all transforms" in the "Transform" drop-down, and pick "pelvis2" (Konoko's). Check the result by alternatively selecting "pelvis" and "pelvis2". Look not only at the values in the "Transform" panel, but also, in any viewport, at the center (white circle) and the local axes (colored) lines. The rotation should be OK, but the translation may be off. If it is, just fix it manually, and check the result in the viewport, alternatively selecting "pelvis" and "pelvis2" until you're sure that both centers are the same.
   • When you're done with "pelvis", move on to "left_thigh". Until now it was a sibling of "pelvis", and a child of "Scene_Root". Now that "pelvis" is done, you can make "left_thigh" a child of "pelvis", by drag-and-dropping it onto "pelvis" in the "Explorer" viewport. Then you need to match the relative transforms of this center with respect to the center of "pelvis". Make sure "Center" is selected in the "Select" panel, then select "left_thigh", choose "Match all transforms" in the "Transform" drop-down, and pick "left_thigh2" (Konoko's posing thigh). Again, the rotation will probably be correct, but the translation will probably be off, and you will have to fix it manually. Check the result by alternatively selecting "left_thigh" and "left_thigh2", until you're happy.
   • Now that you've gotten the idea, do the same for all the other body parts (reparent Gally's, and then match Gally's centers to Konoko's). Make sure you do one mesh at a time, and progress from the root of the tree (the pelvis) towards the extremities. Try not to forget any mesh, especially early on, or you will have to start over.
8. When the matching is over, select all of Gally's meshes, export to Collada ("selection only"), import into Oni and it should Just Work.
9. If there's a problem with any of these steps, just say so. I'm not sure how I could explain it any better without screenshots.