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 different, but at least the feet will be 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. The next (and last) step is to ensure that every new part 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 the Oni character, just select all its meshes, and click "Center" in the top right corner, where the selection filters are.
5. Basically, the only thing that you will be doing is: reparenting the bodyparts of the new character (by drag-and-dropping them in the Scene Explorer) 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.
6. 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 Scene 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.
   • Now, select the left thigh (which is not parented to the new pelvis yet). Drag and drop it into the new pelvis in the Scene Explorer (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). 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 Scene Explorer. 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 at the first steps above, and make sure that you know what you're doing.

This is all done in ModTool I have no idea about how you'd do this in Blender, never tried. geyser

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.