OniGalore - User contributions [en]

Troubleshooting

2025-01-06T22:50:25Z

Delano762: /* Rendering offset from center */

{{UpdatedForOniX|1.0.0}}
==Mac-specific==
See the [[FERAL|Intel Mac build]]'s page for Mac-specific issues.

==Windows-specific==
Most of the problems in Oni itself can be solved by installing a community patch:
*The [[Daodan DLL]] (see that page for manual installation instructions),
*the [[Anniversary Edition]] (installs and updates the Daodan DLL automatically), or you could
*use [[OniX]], the new game application for Windows.

But some problems remain unfixed, so the information below may be useful.

===Installer===
The installer on the CD-ROM, OniSetup.exe, may no longer run in Windows 10. You can extract the game data from the installer's data file (ONISETUP.002) using [https://www.legroom.net/software/uniextract Universal Extractor].

===Blam!s===
Have you seen this message?

[[Image:Blam!.png|center]]

There are several reasons why Oni might exit with such a message. The most common cause is solved by the Daodan DLL and OniX, but if neither of those fixes it…

The [[/Blam|Blam page]] contains a thorough list of things that cause Oni to "blam".

===Mouse/keyboard problems===
See [[Mouse control issues]].

===Low-quality texturing/models===
There are several things that can be go wrong, from fuzzy textures to very-low-detail character models. That's always a driver issue. Try and get a recent driver for your GFX card (upgrade to Catalyst if you have an ATI, etc.). But sometimes, Oni is incompatible with modern stuff. Try and get a really old driver, then :)

===Low frame rate===
;Power management
This can be a problem on notebooks. Under certain conditions, the performance of the computer will decrease dramatically, for example:
*if you run on battery power
*if you let the computer overheat
;Driver issue

First let's make sure that your graphic card has Direct3D and AGP acceleration enabled.
Click on Start, Run, type "dxdiag", and press OK. You will see now various information about your DirectX and your computer hardware/software. Click on display, and check the Direct3D/AGP acceleration checkbox. If it is off, try enabling it, and if it is cannot be enabled, your graphics card may have not have this option, or Windows is using your card as [[wikipedia:Peripheral_Component_Interconnect|PCI]] instead of AGP. In this case, try updating or re-installing all your motherboard drivers.

[[Image:Direct3d acceleration.jpg|thumb|200px|center|Make sure that you have acceleration enabled.]]

Now, if acceleration is enabled like in the picture above, try installing or updating your graphics drivers; don't use the ones that come with Windows. If you have an Nvidia card and if it is old (like GeForce 2 or Riva), I recommend you install an older driver. My recommendation is one from the 28.x and 60.x. range; these seemed to work better with my old card.

Nvidia users can download old drivers [https://www.nvidia.com/en-us/drivers/ here]. ATI users, try [https://www.amd.com/en/support here] (look for the "Previous Drivers" link after finding your card).

See also "Bad texturing", above.

===Widescreen===
To get Oni to support widescreen resolutions, install the Anniversary Edition or just the Daodan DLL.

====Rendering offset from center====
When running the game at wide resolutions (e.g. 3440x1440) it may render offset from center of the screen.

[[Image:Screenshot 2025-01-04 192212.png|400px|center]]
There are three known solutions:
* Set Windows display scaling to 100%,
* Set High DPI scaling override on Oni.exe to Application or try Program DPI on it,
* Get Daodan 4.2 Beta from [https://rossy.oni2.net/daodan-4.2-beta1.zip here],
** Backup binkw32.dll in your <code>\Oni\AE</code> folder,
** Place <code>\build\binkw32.dll</code> from the archive into your \Oni\AE folder.

[[Category:Oni Support]]

Troubleshooting

2025-01-06T22:49:52Z

Delano762:

{{UpdatedForOniX|1.0.0}}
==Mac-specific==
See the [[FERAL|Intel Mac build]]'s page for Mac-specific issues.

==Windows-specific==
Most of the problems in Oni itself can be solved by installing a community patch:
*The [[Daodan DLL]] (see that page for manual installation instructions),
*the [[Anniversary Edition]] (installs and updates the Daodan DLL automatically), or you could
*use [[OniX]], the new game application for Windows.

But some problems remain unfixed, so the information below may be useful.

===Installer===
The installer on the CD-ROM, OniSetup.exe, may no longer run in Windows 10. You can extract the game data from the installer's data file (ONISETUP.002) using [https://www.legroom.net/software/uniextract Universal Extractor].

===Blam!s===
Have you seen this message?

[[Image:Blam!.png|center]]

There are several reasons why Oni might exit with such a message. The most common cause is solved by the Daodan DLL and OniX, but if neither of those fixes it…

The [[/Blam|Blam page]] contains a thorough list of things that cause Oni to "blam".

===Mouse/keyboard problems===
See [[Mouse control issues]].

===Low-quality texturing/models===
There are several things that can be go wrong, from fuzzy textures to very-low-detail character models. That's always a driver issue. Try and get a recent driver for your GFX card (upgrade to Catalyst if you have an ATI, etc.). But sometimes, Oni is incompatible with modern stuff. Try and get a really old driver, then :)

===Low frame rate===
;Power management
This can be a problem on notebooks. Under certain conditions, the performance of the computer will decrease dramatically, for example:
*if you run on battery power
*if you let the computer overheat
;Driver issue

First let's make sure that your graphic card has Direct3D and AGP acceleration enabled.
Click on Start, Run, type "dxdiag", and press OK. You will see now various information about your DirectX and your computer hardware/software. Click on display, and check the Direct3D/AGP acceleration checkbox. If it is off, try enabling it, and if it is cannot be enabled, your graphics card may have not have this option, or Windows is using your card as [[wikipedia:Peripheral_Component_Interconnect|PCI]] instead of AGP. In this case, try updating or re-installing all your motherboard drivers.

[[Image:Direct3d acceleration.jpg|thumb|200px|center|Make sure that you have acceleration enabled.]]

Now, if acceleration is enabled like in the picture above, try installing or updating your graphics drivers; don't use the ones that come with Windows. If you have an Nvidia card and if it is old (like GeForce 2 or Riva), I recommend you install an older driver. My recommendation is one from the 28.x and 60.x. range; these seemed to work better with my old card.

Nvidia users can download old drivers [https://www.nvidia.com/en-us/drivers/ here]. ATI users, try [https://www.amd.com/en/support here] (look for the "Previous Drivers" link after finding your card).

See also "Bad texturing", above.

===Widescreen===
To get Oni to support widescreen resolutions, install the Anniversary Edition or just the Daodan DLL.

====Rendering offset from center====
When running the game at wide resolutions (e.g. 3440x1440) the game may render offset from center of the screen.

[[Image:Screenshot 2025-01-04 192212.png|400px|center]]
There are three known solutions:
* Set Windows display scaling to 100%,
* Set High DPI scaling override on Oni.exe to Application or try Program DPI on it,
* Get Daodan 4.2 Beta from [https://rossy.oni2.net/daodan-4.2-beta1.zip here],
** Backup binkw32.dll in your <code>\Oni\AE</code> folder,
** Place <code>\build\binkw32.dll</code> from the archive into your \Oni\AE folder.

[[Category:Oni Support]]

Troubleshooting

2025-01-06T22:49:28Z

Delano762: Documented the issue with Oni rendering offset from center of the screen

{{UpdatedForOniX|1.0.0}}
==Mac-specific==
See the [[FERAL|Intel Mac build]]'s page for Mac-specific issues.

==Windows-specific==
Most of the problems in Oni itself can be solved by installing a community patch:
*The [[Daodan DLL]] (see that page for manual installation instructions),
*the [[Anniversary Edition]] (installs and updates the Daodan DLL automatically), or you could
*use [[OniX]], the new game application for Windows.

But some problems remain unfixed, so the information below may be useful.

===Installer===
The installer on the CD-ROM, OniSetup.exe, may no longer run in Windows 10. You can extract the game data from the installer's data file (ONISETUP.002) using [https://www.legroom.net/software/uniextract Universal Extractor].

===Blam!s===
Have you seen this message?

[[Image:Blam!.png|center]]

There are several reasons why Oni might exit with such a message. The most common cause is solved by the Daodan DLL and OniX, but if neither of those fixes it…

The [[/Blam|Blam page]] contains a thorough list of things that cause Oni to "blam".

===Mouse/keyboard problems===
See [[Mouse control issues]].

===Low-quality texturing/models===
There are several things that can be go wrong, from fuzzy textures to very-low-detail character models. That's always a driver issue. Try and get a recent driver for your GFX card (upgrade to Catalyst if you have an ATI, etc.). But sometimes, Oni is incompatible with modern stuff. Try and get a really old driver, then :)

===Low frame rate===
;Power management
This can be a problem on notebooks. Under certain conditions, the performance of the computer will decrease dramatically, for example:
*if you run on battery power
*if you let the computer overheat
;Driver issue

First let's make sure that your graphic card has Direct3D and AGP acceleration enabled.
Click on Start, Run, type "dxdiag", and press OK. You will see now various information about your DirectX and your computer hardware/software. Click on display, and check the Direct3D/AGP acceleration checkbox. If it is off, try enabling it, and if it is cannot be enabled, your graphics card may have not have this option, or Windows is using your card as [[wikipedia:Peripheral_Component_Interconnect|PCI]] instead of AGP. In this case, try updating or re-installing all your motherboard drivers.

[[Image:Direct3d acceleration.jpg|thumb|200px|center|Make sure that you have acceleration enabled.]]

Now, if acceleration is enabled like in the picture above, try installing or updating your graphics drivers; don't use the ones that come with Windows. If you have an Nvidia card and if it is old (like GeForce 2 or Riva), I recommend you install an older driver. My recommendation is one from the 28.x and 60.x. range; these seemed to work better with my old card.

Nvidia users can download old drivers [https://www.nvidia.com/en-us/drivers/ here]. ATI users, try [https://www.amd.com/en/support here] (look for the "Previous Drivers" link after finding your card).

See also "Bad texturing", above.

===Widescreen===
To get Oni to support widescreen resolutions, install the Anniversary Edition or just the Daodan DLL.

==Rendering offset from center==
When running the game at wide resolutions (e.g. 3440x1440) the game may render offset from center of the screen.

[[Image:Screenshot 2025-01-04 192212.png|400px|center]]
There are three known solutions:
* Set Windows display scaling to 100%,
* Set High DPI scaling override on Oni.exe to Application or try Program DPI on it,
* Get Daodan 4.2 Beta from [https://rossy.oni2.net/daodan-4.2-beta1.zip here],
** Backup binkw32.dll in your <code>\Oni\AE</code> folder,
** Place <code>\build\binkw32.dll</code> from the archive into your \Oni\AE folder.

[[Category:Oni Support]]

File:Off-center render.png

2025-01-06T22:21:31Z

Delano762:

A screenshot showcasing the issue where Oni renders offset to the screen center.

XML:TRAM

2023-10-16T17:51:36Z

Delano762:

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}

{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

Oni's code and debugging messages tend to spell the word variant as "varient". Blame the programmers for that one. Typically we use the correct spelling here, but OniSplit's XML follows Oni's misspelling, so you may see "varient" creep into the wiki here and there.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here]].

==Open questions==
* If the never-used Thrown type can be applied as type 18 the table looks much more complete. "Restoring" forward tackles (face-to-face, src run + tgt run) can be omitted as the AI would most often stop movement for actual combat?

* All important header data of STRCOMrun_thw_fw_p and STRCOMrun_thw_fw_pl is identical. That means the engine picks the correct TRAM by using an unknown context, possibly this is similar or part of the distinction of "forward" (face-to-face) and "backward" (face-to-back).
: '''Maybe the algorithm checks always tgt's rotation and relative position to src at the same time but for most cases only tgt's rotation (facing) is relevant.'''

* Also, STRCOMrun_thw_fw_p(l) routing to Thrown5 and Thrown6 shows that Thrown anim types might be used however we like. A src-tgt-anim-type-pairing might be simply a ''convention''. Well, someone could check the source code...

* The existence of STRCOMrun_thw_fw_p(_tgt) and STRCOMrun_thw_fw_pl(_t) means that we need extra research to understand the full extent of the throw system.
* The variant pickup system is not clear yet: is a RIFCOM idle and a RIFNAT idle both possible?
** Or do rightpistol, leftpistol, rightrifle and leftrifle variants count as subsets of combat?

==Summary of animation lookup logic==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

===Elaboration===
Animations never stop – they flow from one to another. (See the concept of [[wp:State machine|state machines]] in gaming.) The default case is a character getting spawned and then just standing there: he idles forever. This brings us to the core attributes of every animation: '''type, state, variant'''.

Now then, the idle animation does not link to a specific follow-up animation – it rather links to a follow-up ''state''.
: Ironically all anims have a <FromState> and a <ToState> field, but no obvious <CurrentState> which can cause confusion on what the current anim's state actually is. This gives us two options of how to think about the situation: either consider <FromState> as usually being the <CurrentState>, or states exist only ''between'' anims and serve as ''transition rules''.

Linking to a follow-up state allows for multiple choices of what specific anim comes next. An anim is picked up randomly from a pool of valid anims. Their probability or <Weight> is determined by the anim listing in the TRAC – the anim collection (see "Weights" section for an explanation of exactly how <Weight> is handled).

Anyway, to let an character flow from one anim state to another, the <ToState> is used. Let's say an SBG grenade hits Konoko. The particle's '''damage type''' is '''blownup'''; this and the direction of the incoming damage force an anim of type '''Blownup''' or '''BlownupBehind''' to play, such as TRAMKONOKOblownup1.

Thus, Konoko falls to her back, going into the FallenBack state. The engine picks up the next anim which has <FromState>FallenBack. Also, receiving damage puts a character into combat mode, so further anims will be of variant Combat. But if the player gives no input, Konoko will remain on the ground, as <ToState>FallenBack creates a loop.

So here's a question: why isn't a getup anim like KONCOMgetup_lt played automatically since it also has <FromState>FallenBack and <Varient>Combat? Answer: it differs in its <Type>. Most [[XML_talk:StNA|anim types are bound to user input]] and therefore are excluded from the automatically created pool of valid anims which can follow.

Now let's consider what happens upon user input. A leftward movement of the mouse tells the engine to use an anim of type StandingTurnLeft. There are two anims with that type, KONOKOcomb_turnlt and KONCOMgetup_lt, but only the latter matches the current <FromState> condition.
: In fact, KONOKOcomb_turnlt has <Varient> Combat – the "comb" here stands for "combat", not "combo". Following Oni's naming convention, the file ''should'' have been named KONCOMturn_lt.

Knowing this behavior, we can deduce that anim types registered to user input will make the engine ignore all the automatic anims inside the pool, therefore breaking the loop of KONCOMfallen_back. And since KONCOMgetup_lt has <ToState>Standing and Konoko is still in combat mode, the following idle anim must also have <Varient>Combat. So the next anim played will be KON'''COM'''idle1 or KON'''COM'''idle2.

Konoko will eventually calm down when her ONCC <FightModeTimer> runs down, and then KON'''OKO'''idle1 or KON'''OKO'''idle2 will be played instead. (Actually, the COMidle will continue until a non-combat anim such as running breaks that loop. You won't ever see Konoko drop from combat readiness to her regular idle animation. Instead she will go from combat idle to running, to stopping, then standing at ease.)

Note the fallback behavior of anim lookup: if the engine cannot find an anim for the active variant (or "mode") of the character, it will choose the normal (non-variant-matching) version. Anims can be in the following variants: Combat, LeftPistol, LeftRifle, Panic, RightPistol, RightRifle and Sprint.

As for combinations of variants, it's possible, yes, but rarely and only Sprint and one weapon variant at a time.

==Weights==
Let's say that we're playing as a Ninja, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (no console to interact with), places the character in combat mode, and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 (a spin) and NINCOMtaunt2 (the [[wp:Moon walk|moon walk]] Easter egg). The engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the moon walk taunt.

<TRACAnimation>
<Weight>100</Weight>
<Animation>TRAMNINCOMtaunt1</Animation>
</TRACAnimation>
<TRACAnimation>
<Weight>5</Weight>
<Animation>TRAMNINCOMtaunt2</Animation>
</TRACAnimation>

If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation is: weight of anim / sum of all valid anim weights. For NINCOMtaunt2, this means 5 / 105 = 0.047, or a 4.7% chance of a moon walk.

==Idle timer==
There's a semi-famous Easter egg where [https://www.youtube.com/watch?v=qbo2Q-VD6dc Konoko will sneeze] if she stands still for a long time. The timer for this is so long that most players never see it unless they step away from the game and leave it running without hitting F1. You might think that the way the sneeze is triggered is to set a low weight for it so that it's very unlikely a repeating idle cycle will choose the anim. But here's the sneeze anim in the TRAC with a Weight of 100:

<TRACAnimation>
<Weight>100</Weight>
<Animation>TRAMKONOKOidle_spec3</Animation>
</TRACAnimation>

What's going on here? All regular idle anims are in fact of '''type Stand''', while Konoko's idle_spec3 anim above is of '''type Idle'''. Anims of '''type Idle''' are played every time the idle animation timer expires. This is found in ONCC as <IdleAnimation1Timer> and <IdleAnimation2Timer>. These timers are set to 30,000 for every character. The number is in ticks, so if we convert to minutes – 30,000 / 60 / 60 = 8.3̅ – we find that the secret idle anim for Konoko (or any character) will play every 8⅓ minutes.

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains a Blender addon for automating certain tasks, troubleshooting advice, and links to an animation rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. That being said, Oni has unused combo animation types, such as PKP, PKK, KPK, KPP, etc. that work perfectly fine and can be used to create new combos. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===

====States====
The first anim state of source (src) and target (tgt) is the "primary" <FromState>. The others <FromState> entries are located in <Shortcut>.

====Types====
Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

The game identifies which Target animation is it supposed to play through the ''ThrownX'' animation types. Each throw, together with its corresponding Target animation, uses one of the 17 available ''ThrownX'' animation types. These types are used in three tags:

* <TargetType> tag in the Source animation,
* <Type> and <AimingType> tags in the Target animation.

For example, Konoko's forward punch throw / ''KONCOMthrow_fw_p'' uses Thrown1 as its TargetType tag:

<TargetType>Thrown1</TargetType>

And the corresponding target animation, ''KONCOMthrow_fw_p'', uses Thrown1 in the Type and AimingType tags:

<Type>Thrown1</Type>
<AimingType>Thrown1</AimingType>

The ''ThrownX'' anim types work like slots - if you want to add a new throw to the game, you have to assign both the Source and the Target animations the same ThrownX type in the tags listed above. While these "pairs" are organized within vanilla animations according to the Throw Table below, this is nothing more than a convention, and as a result ''ThrownX'' types can be used freely. To give an example, while all Forward Punch Throws in the game seem to use the Thrown1 type, you can swap those types with another throw and they will work just as fine.

The fact that the game has only 17 ''ThrownX'' types is a major limitation - this effectively means that each character can have no more than 17 throws - out of which only 4 are unused by any character in the game. This prevents modders from creating a significant number of throws despite the game allowing great flexibility in creating new throws by mixing Animation States, Animation Types and <Varient> tags.

{{divhide|Throw table}}
{| class="wikitable" width=100%
|-
! rowspan=2 width=240 | names
! rowspan=2 width=40 | key combo
! colspan=4 | context
! colspan=2 style="background: #FF0;" | anim type
! rowspan=2 width=400 | image
|-

! width=40 | varient
! width=60 | src state
! width=60 | tgt state
! width=85 | facing setup



! width=40 style="background: #FF0;" | src
! width=40 style="background: #FF0;" | tgt
|-
! colspan=9 | normal throws a.k.a. static throws
|- style="vertical-align:top;"
| static throw forward punch
: TRAMKONCOMthrow_fw_p
: TRAMKONCOMthrow_fw_p_tgt
| P + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown1'''
| [[image:KONCOMthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| static throw forward kick
: TRAMKONCOMthrow_fw_k
: TRAMKONCOMthrow_fw_k_tgt
| K + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardKick'''
| '''Thrown2'''
| [[image:KONCOMthrow_fw_k.jpg|200px]]
|-style="vertical-align:top;"
| static throw backward punch
: TRAMKONCOMthrow_bk
: TRAMKONCOMthrow_bk_tgt
| P + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown3'''
| [[image:KONCOMthrow_bk.jpg|200px]]
|-style="vertical-align:top;"
| static throw backward punch
: TRAMKONCOMthrow_bk_k
: TRAMKONCOMthrow_bk_k_tgt
| K + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardKick'''
| '''Thrown4'''
| [[image:KONCOMthrow_bk_k.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | run throws
|-style="vertical-align:top;"
| run throw forward punch
: (forward "lariat")
: TRAMKONCOMrun_throw_fw
: TRAMKONCOMrun_throw_fw_tgt
| P + ↑(↑)
| COM
| '''None'''

RunningLeftDown 
RunningRightDown
| '''Standing'''

RunningLeftDown 
RunningRightDown 
Stunned 
WalkingLeftDown 
WalkingRightDown 
| face-to-'''face'''
| '''RunThrowForwardPunch'''
| '''Thrown5'''
| [[image:KONCOMrun_throw_fw.jpg|200px]]
|-style="vertical-align:top;"
| run throw forward kick
: TRAMKONCOMrun_thw_fw_k
: TRAMKONCOMrun_thw_fw_k_tgt
| K + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningLeftDown 
RunningRightDown 
Stunned 
WalkingLeftDown 
WalkingRightDown
| face-to-'''face'''
| '''RunThrowForwardKick'''
| '''Thrown6'''
| [[image:KONCOMrun_thw_fw_k.jpg|200px]]

|-style="vertical-align:top;"
| run throw backward punch
: (backward "lariat")
: TRAMKONCOMrun_throw_bk
: TRAMKONCOMrun_throw_bk_tgt
| P + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningBackLeftDown 
RunningBackRightDown 
WalkingRightDown 
WalkingLeftDown 
Stunned

| face-to-'''back'''
| '''RunThrowBackwardPunch'''
| '''Thrown7'''
|
|-style="vertical-align:top;"
| run throw backward kick
: TRAMREDCOMrun_thw_bk_k
: TRAMREDCOMrun_thw_bk_k_tgt
| K + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningBackLeftDown 
RunningBackRightDown 
Stunned
| face-to-'''back'''
| '''RunThrowBackwardKick'''
| '''Thrown8'''
| [[image:REDCOMrun_thw_bk_k.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | catching throws a.k.a. tackle throws
|-style="vertical-align:top;"
| tackle throw backward kick? (never used)
|
|
|
|
|
|
| Thrown9
|
|-style="vertical-align:top;"
| tackle throw backward punch
: TRAMKONCOMrun_tkl_bk_p
: TRAMKONCOMrun_tkl_bk_p_tgt
| P + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''None'''

RunningLeftDown 
RunningRightDown
| face-to-'''back'''
| '''RunThrowBackwardPunch'''
| '''Thrown10'''
| [[image:KONCOMrun_tkl_bk_p.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | disarm throws
|-style="vertical-align:top;"
| pistol disarm throw forward punch
: TRAMKONPISthrow_fw_p
: TRAMKONPISthrow_fw_p_tgt
| P + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown11'''
| [[image:KONPISthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| pistol disarm throw forward kick
: TRAMKONPISthrow_fw_k
: TRAMKONPISthrow_fw_k_tgt
| K + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardKick'''
| '''Thrown12'''
| [[image:KONPISthrow_fw_k.jpg|200px]]
|-style="vertical-align:top;"
| pistol disarm throw backward punch
: TRAMKONPISthrow_bk
: TRAMKONPISthrow_bk_tgt
| P + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown13'''
| [[image:KONPISthrow_bk.jpg|200px]]
|-style="vertical-align:top;"
| (never used)
|
|
|
|
|
|
| Thrown14
|
|-style="vertical-align:top;"
| rifle disarm throw forward punch
: TRAMKONRIFthrow_fw_p
: TRAMKONRIFthrow_fw_p_tgt
| P + ↑
| RIF
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown15'''
| [[image:KONRIFthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| rifle disarm throw backward punch
: TRAMKONRIFthrow_bk_p
: TRAMKONRIFthrow_bk_p_tgt
| P + ↑
| RIF
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown16'''
| [[image:KONRIFthrow_bk_p.jpg|200px]]
|-style="vertical-align:top;"
| (never used)
|
|
|
|
|
|
| Thrown17
|
|}
{{divhide|end}}

Looks like there was/is support for [[OBD:BINA/OBJC/MELE/MoveList/Throw|running disarms]]. Though unused types for new Thrown''N'' would be needed. On second thought, one should check if we can't simply make a '''running (tgt + src) variant''' of disarms.

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]
Motion blur in Oni works much like ghosting/onion skinning features in any animation software: In the frame range specified by <Start> and <End> an additional instance of body parts specified in <Bones> are rendered for additional extra frames specified by <Lifetime>, with transparency set by <Alpha>, and every <Interval> frames within the frame range.
Example snippet from KONCOMcomb_p_p_k:
<MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

The one noteworthy thing is that you can have multiple motion blur sequences. If you wanted to add an extra motion blur to the above animation, you could do something like this:
<MotionBlur>
<MotionBlur>
<Bones>LeftThigh LeftCalf LeftFoot</Bones>
<Start>10</Start>
<End>18</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

===Impact effect===
Impact effects – mostly particle – are chosen based on logic written within [[XML:BINA/ONIE#Visual guides: weapon, melee, environment|ONIE]]. Furthermore particles must be registered in [[XML:ONCC|ONCC]]: You probably want to look at ONIA instead of ONCP.

[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

{{XML}}

XML:TRAM

2023-10-16T17:00:30Z

Delano762: Reworked the Throws section. Removed the information on forward/back naming pattern, as forward/back/left/right is a naming convention for input direction in the game, therefore it isn't even specific to throws. Will continue reworking this section later.

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}

{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

Oni's code and debugging messages tend to spell the word variant as "varient". Blame the programmers for that one. Typically we use the correct spelling here, but OniSplit's XML follows Oni's misspelling, so you may see "varient" creep into the wiki here and there.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here]].

==Open questions==
* If the never-used Thrown type can be applied as type 18 the table looks much more complete. "Restoring" forward tackles (face-to-face, src run + tgt run) can be omitted as the AI would most often stop movement for actual combat?

* All important header data of STRCOMrun_thw_fw_p and STRCOMrun_thw_fw_pl is identical. That means the engine picks the correct TRAM by using an unknown context, possibly this is similar or part of the distinction of "forward" (face-to-face) and "backward" (face-to-back).
: '''Maybe the algorithm checks always tgt's rotation and relative position to src at the same time but for most cases only tgt's rotation (facing) is relevant.'''

* Also, STRCOMrun_thw_fw_p(l) routing to Thrown5 and Thrown6 shows that Thrown anim types might be used however we like. A src-tgt-anim-type-pairing might be simply a ''convention''. Well, someone could check the source code...

* The existence of STRCOMrun_thw_fw_p(_tgt) and STRCOMrun_thw_fw_pl(_t) means that we need extra research to understand the full extent of the throw system.
* The variant pickup system is not clear yet: is a RIFCOM idle and a RIFNAT idle both possible?
** Or do rightpistol, leftpistol, rightrifle and leftrifle variants count as subsets of combat?

==Summary of animation lookup logic==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

===Elaboration===
Animations never stop – they flow from one to another. (See the concept of [[wp:State machine|state machines]] in gaming.) The default case is a character getting spawned and then just standing there: he idles forever. This brings us to the core attributes of every animation: '''type, state, variant'''.

Now then, the idle animation does not link to a specific follow-up animation – it rather links to a follow-up ''state''.
: Ironically all anims have a <FromState> and a <ToState> field, but no obvious <CurrentState> which can cause confusion on what the current anim's state actually is. This gives us two options of how to think about the situation: either consider <FromState> as usually being the <CurrentState>, or states exist only ''between'' anims and serve as ''transition rules''.

Linking to a follow-up state allows for multiple choices of what specific anim comes next. An anim is picked up randomly from a pool of valid anims. Their probability or <Weight> is determined by the anim listing in the TRAC – the anim collection (see "Weights" section for an explanation of exactly how <Weight> is handled).

Anyway, to let an character flow from one anim state to another, the <ToState> is used. Let's say an SBG grenade hits Konoko. The particle's '''damage type''' is '''blownup'''; this and the direction of the incoming damage force an anim of type '''Blownup''' or '''BlownupBehind''' to play, such as TRAMKONOKOblownup1.

Thus, Konoko falls to her back, going into the FallenBack state. The engine picks up the next anim which has <FromState>FallenBack. Also, receiving damage puts a character into combat mode, so further anims will be of variant Combat. But if the player gives no input, Konoko will remain on the ground, as <ToState>FallenBack creates a loop.

So here's a question: why isn't a getup anim like KONCOMgetup_lt played automatically since it also has <FromState>FallenBack and <Varient>Combat? Answer: it differs in its <Type>. Most [[XML_talk:StNA|anim types are bound to user input]] and therefore are excluded from the automatically created pool of valid anims which can follow.

Now let's consider what happens upon user input. A leftward movement of the mouse tells the engine to use an anim of type StandingTurnLeft. There are two anims with that type, KONOKOcomb_turnlt and KONCOMgetup_lt, but only the latter matches the current <FromState> condition.
: In fact, KONOKOcomb_turnlt has <Varient> Combat – the "comb" here stands for "combat", not "combo". Following Oni's naming convention, the file ''should'' have been named KONCOMturn_lt.

Knowing this behavior, we can deduce that anim types registered to user input will make the engine ignore all the automatic anims inside the pool, therefore breaking the loop of KONCOMfallen_back. And since KONCOMgetup_lt has <ToState>Standing and Konoko is still in combat mode, the following idle anim must also have <Varient>Combat. So the next anim played will be KON'''COM'''idle1 or KON'''COM'''idle2.

Konoko will eventually calm down when her ONCC <FightModeTimer> runs down, and then KON'''OKO'''idle1 or KON'''OKO'''idle2 will be played instead. (Actually, the COMidle will continue until a non-combat anim such as running breaks that loop. You won't ever see Konoko drop from combat readiness to her regular idle animation. Instead she will go from combat idle to running, to stopping, then standing at ease.)

Note the fallback behavior of anim lookup: if the engine cannot find an anim for the active variant (or "mode") of the character, it will choose the normal (non-variant-matching) version. Anims can be in the following variants: Combat, LeftPistol, LeftRifle, Panic, RightPistol, RightRifle and Sprint.

As for combinations of variants, it's possible, yes, but rarely and only Sprint and one weapon variant at a time.

==Weights==
Let's say that we're playing as a Ninja, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (no console to interact with), places the character in combat mode, and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 (a spin) and NINCOMtaunt2 (the [[wp:Moon walk|moon walk]] Easter egg). The engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the moon walk taunt.

<TRACAnimation>
<Weight>100</Weight>
<Animation>TRAMNINCOMtaunt1</Animation>
</TRACAnimation>
<TRACAnimation>
<Weight>5</Weight>
<Animation>TRAMNINCOMtaunt2</Animation>
</TRACAnimation>

If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation is: weight of anim / sum of all valid anim weights. For NINCOMtaunt2, this means 5 / 105 = 0.047, or a 4.7% chance of a moon walk.

==Idle timer==
There's a semi-famous Easter egg where [https://www.youtube.com/watch?v=qbo2Q-VD6dc Konoko will sneeze] if she stands still for a long time. The timer for this is so long that most players never see it unless they step away from the game and leave it running without hitting F1. You might think that the way the sneeze is triggered is to set a low weight for it so that it's very unlikely a repeating idle cycle will choose the anim. But here's the sneeze anim in the TRAC with a Weight of 100:

<TRACAnimation>
<Weight>100</Weight>
<Animation>TRAMKONOKOidle_spec3</Animation>
</TRACAnimation>

What's going on here? All regular idle anims are in fact of '''type Stand''', while Konoko's idle_spec3 anim above is of '''type Idle'''. Anims of '''type Idle''' are played every time the idle animation timer expires. This is found in ONCC as <IdleAnimation1Timer> and <IdleAnimation2Timer>. These timers are set to 30,000 for every character. The number is in ticks, so if we convert to minutes – 30,000 / 60 / 60 = 8.3̅ – we find that the secret idle anim for Konoko (or any character) will play every 8⅓ minutes.

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains a Blender addon for automating certain tasks, troubleshooting advice, and links to an animation rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. That being said, Oni has unused combo animation types, such as PKP, PKK, KPK, KPP, etc. that work perfectly fine and can be used to create new combos. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===

==States==
The first anim state of source (src) and target (tgt) is the "primary" <FromState>. The others <FromState> entries are located in <Shortcut>.

==Types==
Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

The game identifies which Target animation is it supposed to play through the ''ThrownX'' animation types. Each throw, together with its corresponding Target animation, uses one of the 17 available ''ThrownX'' animation types. These types are used in three tags:

* <TargetType> tag in the Source animation,
* <Type> and <AimingType> tags in the Target animation.

For example, Konoko's forward punch throw / ''KONCOMthrow_fw_p'' uses Thrown1 as its TargetType tag:

<TargetType>Thrown1</TargetType>

And the corresponding target animation, ''KONCOMthrow_fw_p'', uses Thrown1 in the Type and AimingType tags:

<Type>Thrown1</Type>
<AimingType>Thrown1</AimingType>

The ''ThrownX'' anim types work like slots - if you want to add a new throw to the game, you have to assign both the Source and the Target animations the same ThrownX type in the tags listed above. While these "pairs" are organized within vanilla animations according to the Throw Table below, this is nothing more than a convention, and as a result ''ThrownX'' types can be used freely. To give an example, while all Forward Punch Throws in the game seem to use the Thrown1 type, you can swap those types with another throw and they will work just as fine.

The fact that the game has only 17 ''ThrownX'' types is a major limitation - this effectively means that each character can have no more than 17 throws - out of which only 4 are unused by any character in the game. This prevents modders from creating a significant number of throws despite the game allowing great flexibility in creating new throws by mixing Animation States, Animation Types and <Varient> tags.

{{divhide|Throw table}}
{| class="wikitable" width=100%
|-
! rowspan=2 width=240 | names
! rowspan=2 width=40 | key combo
! colspan=4 | context
! colspan=2 style="background: #FF0;" | anim type
! rowspan=2 width=400 | image
|-

! width=40 | varient
! width=60 | src state
! width=60 | tgt state
! width=85 | facing setup



! width=40 style="background: #FF0;" | src
! width=40 style="background: #FF0;" | tgt
|-
! colspan=9 | normal throws a.k.a. static throws
|- style="vertical-align:top;"
| static throw forward punch
: TRAMKONCOMthrow_fw_p
: TRAMKONCOMthrow_fw_p_tgt
| P + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown1'''
| [[image:KONCOMthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| static throw forward kick
: TRAMKONCOMthrow_fw_k
: TRAMKONCOMthrow_fw_k_tgt
| K + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardKick'''
| '''Thrown2'''
| [[image:KONCOMthrow_fw_k.jpg|200px]]
|-style="vertical-align:top;"
| static throw backward punch
: TRAMKONCOMthrow_bk
: TRAMKONCOMthrow_bk_tgt
| P + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown3'''
| [[image:KONCOMthrow_bk.jpg|200px]]
|-style="vertical-align:top;"
| static throw backward punch
: TRAMKONCOMthrow_bk_k
: TRAMKONCOMthrow_bk_k_tgt
| K + ↑
| COM
| '''Standing'''

RunStart
| '''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardKick'''
| '''Thrown4'''
| [[image:KONCOMthrow_bk_k.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | run throws
|-style="vertical-align:top;"
| run throw forward punch
: (forward "lariat")
: TRAMKONCOMrun_throw_fw
: TRAMKONCOMrun_throw_fw_tgt
| P + ↑(↑)
| COM
| '''None'''

RunningLeftDown 
RunningRightDown
| '''Standing'''

RunningLeftDown 
RunningRightDown 
Stunned 
WalkingLeftDown 
WalkingRightDown 
| face-to-'''face'''
| '''RunThrowForwardPunch'''
| '''Thrown5'''
| [[image:KONCOMrun_throw_fw.jpg|200px]]
|-style="vertical-align:top;"
| run throw forward kick
: TRAMKONCOMrun_thw_fw_k
: TRAMKONCOMrun_thw_fw_k_tgt
| K + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningLeftDown 
RunningRightDown 
Stunned 
WalkingLeftDown 
WalkingRightDown
| face-to-'''face'''
| '''RunThrowForwardKick'''
| '''Thrown6'''
| [[image:KONCOMrun_thw_fw_k.jpg|200px]]

|-style="vertical-align:top;"
| run throw backward punch
: (backward "lariat")
: TRAMKONCOMrun_throw_bk
: TRAMKONCOMrun_throw_bk_tgt
| P + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningBackLeftDown 
RunningBackRightDown 
WalkingRightDown 
WalkingLeftDown 
Stunned

| face-to-'''back'''
| '''RunThrowBackwardPunch'''
| '''Thrown7'''
|
|-style="vertical-align:top;"
| run throw backward kick
: TRAMREDCOMrun_thw_bk_k
: TRAMREDCOMrun_thw_bk_k_tgt
| K + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''Standing'''

RunningBackLeftDown 
RunningBackRightDown 
Stunned
| face-to-'''back'''
| '''RunThrowBackwardKick'''
| '''Thrown8'''
| [[image:REDCOMrun_thw_bk_k.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | catching throws a.k.a. tackle throws
|-style="vertical-align:top;"
| tackle throw backward kick? (never used)
|
|
|
|
|
|
| Thrown9
|
|-style="vertical-align:top;"
| tackle throw backward punch
: TRAMKONCOMrun_tkl_bk_p
: TRAMKONCOMrun_tkl_bk_p_tgt
| P + ↑(↑)
| COM
|'''None'''

RunningLeftDown 
RunningRightDown
|'''None'''

RunningLeftDown 
RunningRightDown
| face-to-'''back'''
| '''RunThrowBackwardPunch'''
| '''Thrown10'''
| [[image:KONCOMrun_tkl_bk_p.jpg|200px]]
|-style="vertical-align:top;"
! colspan=9 | disarm throws
|-style="vertical-align:top;"
| pistol disarm throw forward punch
: TRAMKONPISthrow_fw_p
: TRAMKONPISthrow_fw_p_tgt
| P + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown11'''
| [[image:KONPISthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| pistol disarm throw forward kick
: TRAMKONPISthrow_fw_k
: TRAMKONPISthrow_fw_k_tgt
| K + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardKick'''
| '''Thrown12'''
| [[image:KONPISthrow_fw_k.jpg|200px]]
|-style="vertical-align:top;"
| pistol disarm throw backward punch
: TRAMKONPISthrow_bk
: TRAMKONPISthrow_bk_tgt
| P + ↑
| PIS
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
WalkingLeftDown 
WalkingRightDown 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown13'''
| [[image:KONPISthrow_bk.jpg|200px]]
|-style="vertical-align:top;"
| (never used)
|
|
|
|
|
|
| Thrown14
|
|-style="vertical-align:top;"
| rifle disarm throw forward punch
: TRAMKONRIFthrow_fw_p
: TRAMKONRIFthrow_fw_p_tgt
| P + ↑
| RIF
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''face'''
| '''ThrowForwardPunch'''
| '''Thrown15'''
| [[image:KONRIFthrow_fw_p.jpg|200px]]
|-style="vertical-align:top;"
| rifle disarm throw backward punch
: TRAMKONRIFthrow_bk_p
: TRAMKONRIFthrow_bk_p_tgt
| P + ↑
| RIF
|'''Standing'''

RunStart
|'''Standing'''

Crouch 
Stunned
| face-to-'''back'''
| '''ThrowBackwardPunch'''
| '''Thrown16'''
| [[image:KONRIFthrow_bk_p.jpg|200px]]
|-style="vertical-align:top;"
| (never used)
|
|
|
|
|
|
| Thrown17
|
|}
{{divhide|end}}

Looks like there was/is support for [[OBD:BINA/OBJC/MELE/MoveList/Throw|running disarms]]. Though unused types for new Thrown''N'' would be needed. On second thought, one should check if we can't simply make a '''running (tgt + src) variant''' of disarms.

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]
Motion blur in Oni works much like ghosting/onion skinning features in any animation software: In the frame range specified by <Start> and <End> an additional instance of body parts specified in <Bones> are rendered for additional extra frames specified by <Lifetime>, with transparency set by <Alpha>, and every <Interval> frames within the frame range.
Example snippet from KONCOMcomb_p_p_k:
<MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

The one noteworthy thing is that you can have multiple motion blur sequences. If you wanted to add an extra motion blur to the above animation, you could do something like this:
<MotionBlur>
<MotionBlur>
<Bones>LeftThigh LeftCalf LeftFoot</Bones>
<Start>10</Start>
<End>18</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

===Impact effect===
Impact effects – mostly particle – are chosen based on logic written within [[XML:BINA/ONIE#Visual guides: weapon, melee, environment|ONIE]]. Furthermore particles must be registered in [[XML:ONCC|ONCC]]: You probably want to look at ONIA instead of ONCP.

[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

{{XML}}

XML:TRAM

2023-10-08T18:20:50Z

Delano762: /* Combos */ Added information on unused combo animation types

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}
{{update}}
{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here.]]

==Decision path of animation lookup==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML_talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

Detailed example: Let's say that we shapeshifted to a Ninja ONCC, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (a hostile character to interact with) and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 and NINCOMtaunt2. If there are multiple anims available at this point, the engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the Moon Walk taunt.

Keep in mind that if the engine cannot find an anim of a specific variant, it will fall back to a non-variant anim instead.

Confused by how Weights work? Apparently, the Weight value is only one part of the equation — otherwise NINCOMtaunt2 would never execute. If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation seems to be: weight / sum of all weights. For NINCOMtaunt2, this means 5 / 105 = 0.047 (4.7%).

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains a Blender addon for automating certain tasks, troubleshooting advice, and links to an animation rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. That being said, Oni has unused combo animation types, such as PKP, PKK, KPK, KPP, etc. that work perfectly fine and can be used to create new combos. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===
: Todo: Add here throw pair table from talk page when it is complete.

Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character, removing the need to have that animation in the target's TRAC. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

====Excel macro====
[[Image:Animation_macro_v4.png|right|thumb]]
The Excel macro can be used to create any TRAM except overlays. [https://www.youtube.com/watch?v=vDTPYfvMf4M Demo vid here].

The macro should be rewritten as a .NET framework or application because Excel is not freeware. However, the tool was made with XSI in mind (for getting animation pair-based information). As XSI is mostly considered obsolete by the community, research for doing the same with Blender will be needed.

There was some development of a .NET-based '''[[TRAM setup assistant]]''' in 2016, but the work drifted into inactivity since the community showed no sign of demand for an updated tool.

As of now there is a Blender script for creating throw target adjustment data. So instead of writing a new stand-alone app, at least the creation of header data might be better ported to the Blender script.

'''Macro usage:'''
* Put your files into the "input_and_output" folder.
* Disable macro security if you don't want to have to click on the "Enable Content" button every time.
* Close other worksheets before you run the macro.
* If you are not afraid of VBA code, you can enter the dev environment by hitting Alt+F11. If you want to extend the attack library with more screenshots and settings, search for "LibraryThrows", "LibraryAttack", "Picture", and "CBAttackHelp.AddItem".

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]
Motion blur in Oni works much like ghosting/onion skinning features in any animation software: In the frame range specified by <Start> and <End> an additional instance of body parts specified in <Bones> are rendered for additional extra frames specified by <Lifetime>, with transparency set by <Alpha>, and every <Interval> frames within the frame range.
Example snippet from KONCOMcomb_p_p_k:
<MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

The one noteworthy thing is that you can have multiple motion blur sequences. If you wanted to add an extra motion blur to the above animation, you could do something like this:
<MotionBlur>
<MotionBlur>
<Bones>LeftThigh LeftCalf LeftFoot</Bones>
<Start>10</Start>
<End>18</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

===Impact effect===
[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

See also [[XML:ONCC]].

{{XML}}

XML:TRAM

2023-10-08T13:33:45Z

Delano762: /* Blender */

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}
{{update}}
{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here.]]

==Decision path of animation lookup==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML_talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

Detailed example: Let's say that we shapeshifted to a Ninja ONCC, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (a hostile character to interact with) and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 and NINCOMtaunt2. If there are multiple anims available at this point, the engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the Moon Walk taunt.

Keep in mind that if the engine cannot find an anim of a specific variant, it will fall back to a non-variant anim instead.

Confused by how Weights work? Apparently, the Weight value is only one part of the equation — otherwise NINCOMtaunt2 would never execute. If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation seems to be: weight / sum of all weights. For NINCOMtaunt2, this means 5 / 105 = 0.047 (4.7%).

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains a Blender addon for automating certain tasks, troubleshooting advice, and links to an animation rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===
: Todo: Add here throw pair table from talk page when it is complete.

Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character, removing the need to have that animation in the target's TRAC. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

====Excel macro====
[[Image:Animation_macro_v4.png|right|thumb]]
The Excel macro can be used to create any TRAM except overlays. [https://www.youtube.com/watch?v=vDTPYfvMf4M Demo vid here].

The macro should be rewritten as a .NET framework or application because Excel is not freeware. However, the tool was made with XSI in mind (for getting animation pair-based information). As XSI is mostly considered obsolete by the community, research for doing the same with Blender will be needed.

There was some development of a .NET-based '''[[TRAM setup assistant]]''' in 2016, but the work drifted into inactivity since the community showed no sign of demand for an updated tool.

As of now there is a Blender script for creating throw target adjustment data. So instead of writing a new stand-alone app, at least the creation of header data might be better ported to the Blender script.

'''Macro usage:'''
* Put your files into the "input_and_output" folder.
* Disable macro security if you don't want to have to click on the "Enable Content" button every time.
* Close other worksheets before you run the macro.
* If you are not afraid of VBA code, you can enter the dev environment by hitting Alt+F11. If you want to extend the attack library with more screenshots and settings, search for "LibraryThrows", "LibraryAttack", "Picture", and "CBAttackHelp.AddItem".

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]
Motion blur in Oni works much like ghosting/onion skinning features in any animation software: In the frame range specified by <Start> and <End> an additional instance of body parts specified in <Bones> are rendered for additional extra frames specified by <Lifetime>, with transparency set by <Alpha>, and every <Interval> frames within the frame range.
Example snippet from KONCOMcomb_p_p_k:
<MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

The one noteworthy thing is that you can have multiple motion blur sequences. If you wanted to add an extra motion blur to the above animation, you could do something like this:
<MotionBlur>
<MotionBlur>
<Bones>LeftThigh LeftCalf LeftFoot</Bones>
<Start>10</Start>
<End>18</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

===Impact effect===
[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

See also [[XML:ONCC]].

{{XML}}

XML:TRAM

2023-10-08T13:13:55Z

Delano762: /* Motion blur */ Explained how motion blur works and added info on how you can have multiple sequences, which is about the only thing you can make any tutorial on, in this otherwise self-explanatory part

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}
{{update}}
{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here.]]

==Decision path of animation lookup==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML_talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

Detailed example: Let's say that we shapeshifted to a Ninja ONCC, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (a hostile character to interact with) and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 and NINCOMtaunt2. If there are multiple anims available at this point, the engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the Moon Walk taunt.

Keep in mind that if the engine cannot find an anim of a specific variant, it will fall back to a non-variant anim instead.

Confused by how Weights work? Apparently, the Weight value is only one part of the equation — otherwise NINCOMtaunt2 would never execute. If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation seems to be: weight / sum of all weights. For NINCOMtaunt2, this means 5 / 105 = 0.047 (4.7%).

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains code snippets for automating certain tasks, troubleshooting advice, and links to an IK rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===
: Todo: Add here throw pair table from talk page when it is complete.

Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character, removing the need to have that animation in the target's TRAC. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

====Excel macro====
[[Image:Animation_macro_v4.png|right|thumb]]
The Excel macro can be used to create any TRAM except overlays. [https://www.youtube.com/watch?v=vDTPYfvMf4M Demo vid here].

The macro should be rewritten as a .NET framework or application because Excel is not freeware. However, the tool was made with XSI in mind (for getting animation pair-based information). As XSI is mostly considered obsolete by the community, research for doing the same with Blender will be needed.

There was some development of a .NET-based '''[[TRAM setup assistant]]''' in 2016, but the work drifted into inactivity since the community showed no sign of demand for an updated tool.

As of now there is a Blender script for creating throw target adjustment data. So instead of writing a new stand-alone app, at least the creation of header data might be better ported to the Blender script.

'''Macro usage:'''
* Put your files into the "input_and_output" folder.
* Disable macro security if you don't want to have to click on the "Enable Content" button every time.
* Close other worksheets before you run the macro.
* If you are not afraid of VBA code, you can enter the dev environment by hitting Alt+F11. If you want to extend the attack library with more screenshots and settings, search for "LibraryThrows", "LibraryAttack", "Picture", and "CBAttackHelp.AddItem".

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]
Motion blur in Oni works much like ghosting/onion skinning features in any animation software: In the frame range specified by <Start> and <End> an additional instance of body parts specified in <Bones> are rendered for additional extra frames specified by <Lifetime>, with transparency set by <Alpha>, and every <Interval> frames within the frame range.
Example snippet from KONCOMcomb_p_p_k:
<MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

The one noteworthy thing is that you can have multiple motion blur sequences. If you wanted to add an extra motion blur to the above animation, you could do something like this:
<MotionBlur>
<MotionBlur>
<Bones>LeftThigh LeftCalf LeftFoot</Bones>
<Start>10</Start>
<End>18</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
<MotionBlur>
<Bones>RightThigh RightCalf RightFoot</Bones>
<Start>20</Start>
<End>28</End>
<Lifetime>4</Lifetime>
<Alpha>127</Alpha>
<Interval>1</Interval>
</MotionBlur>
</MotionBlur>

===Impact effect===
[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

See also [[XML:ONCC]].

{{XML}}

XML:TRAM

2023-10-08T12:34:45Z

Delano762: /* List of tags, types, and flags */ Explained motion blur tags based on info in https://wiki.oni2.net/OBD:TRAM/raw0x1C

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}
{{update}}
{{TOCfloat|side=right}}
==General information==
TRAM files — animation data for characters — are basically made of three chunks:
* Metadata or "header": animation type, state, flags, particle, sounds, etc.
* Animation data: '''pelvis heights, pelvis velocities (root motion)''', bone rotations
* Attack data: damage, self-damage, extents (danger zones for AI awareness) and throws

Root motion: a character moves by changing the position of its root bone (pelvis). The animated legs just create the '''illusion for the player''' that they are responsible for the motion.

Bones: Each character has '''19 separate body parts''' which get animated (rotated) relative to each other. Compared to modern games Oni's bone system is [[wp:Deprecation|deprecated]]. The body doesn't get deformed by following animated bones. Oni modders often use the terms mesh and bone interchangeably. Only the pelvis has '''translation''' data (heights and velocities) besides rotations. The hierarchy of the body parts (or bones) is determined by [[XML:TRBS#Standard_TRIA_hierarchy|TRIA]].

The term '''animation''' is often shortened to '''anim''' by modders, following the naming of commands in BSL: chr_wait_animstate, chr_wait_animtype, env_anim, etc.

TRAMs used in Oni follow a naming pattern. A list of all combat TRAMs in-game and their naming can be found [[Combat moves|here.]]

==Decision path of animation lookup==
* First the game builds a pool of anims a character can use. They are loaded from the TRAC file registered in [[ONCC]], including parent TRACs.
* Anims from a child TRAC override those of the parent if their combination of state, type and variant is exactly the same.
* Child TRACs usually omit some anims. For example, Elite Strikers don't have their own run anims, so they use the parent anims of normal Strikers. See [[XML:TRAC|TRAC]] page for details.
* A character always possesses a single animation state. This term derives from state machines, but you only need to know that states are the first point in the decision path determining what anims are actually allowed to play at a given moment.
* Here is the full decision path:
** anim '''state''' check
** event (user input, or engine input for the AI) -> [[XML_talk:StNA|context check]] -> anim '''type''' check
** anim '''variant''' check
** TRAC '''weight''' check

Detailed example: Let's say that we shapeshifted to a Ninja ONCC, we are in the state Standing, and we hit the action key to perform a taunt. The engine recognizes the context (a hostile character to interact with) and looks up anims of type Taunt. Since we are in combat mode, the next anim must be of variant Combat if possible. These lookups boil down to two valid possible anims: NINCOMtaunt1 and NINCOMtaunt2. If there are multiple anims available at this point, the engine picks one of them randomly.

However, NINCOMtaunt1 has a TRAC Weight (probability) of 100 while NINCOMtaunt2 has a TRAC Weight value of just 5. So the chances are quite high that we will not see the Moon Walk taunt.

Keep in mind that if the engine cannot find an anim of a specific variant, it will fall back to a non-variant anim instead.

Confused by how Weights work? Apparently, the Weight value is only one part of the equation — otherwise NINCOMtaunt2 would never execute. If there is only one anim to choose from, it will always play no matter what its Weight, even if it is zero. When it comes to multiple anims being a valid choice, the calculation seems to be: weight / sum of all weights. For NINCOMtaunt2, this means 5 / 105 = 0.047 (4.7%).

==List of tags, types, and flags==
Use the search function in your browser to quickly find a tag.

{| class="wikitable" width=100%
|width=120px| '''tag'''
|width=100px| '''type'''
| '''description'''
|-
| <Lookup>
| parent tag
|
|-
| <Type>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs (animations a character can choose from) is built from the TRAC files registered in the ONCC. Most of the anim types are connected to player inputs.
|-
| <AimingType>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]]. The pool of valid TRAMs, and therefore TRASs (aiming screens a character can choose from) is built from the TRSC files registered in the ONCC.
:
|-
|valign="top"| <FromState>
|valign="top"| flag
| [[Image:chr_debug_characters_shows_interpolated_animations.jpg|thumb|400px|right|Primary <FromState> in <Lookup> uses about 8 interpolating frames by default. Use Shortcut's <FromState> to override this frame number.]]

Look them up over [[XML:StNA#Animation_states|HERE]].
: When FromState is set to None, some default behaviors are ignored and are replaced by Shortcuts.
: Shortcuts extend the number of states from which an animation can be played and under what conditions (replacing this atomic yes/no).
|-
| <ToState>
| flag
| Look them up over [[XML:StNA#Animation_states|HERE]].
|-
|valign="top"| <Varient>
|valign="top"| flag
|(misspelled because Oni misspells it) If unused, the tag will simply be "<Varient />", such as for non-combat animations. Otherwise it contains one of these values:
: Combat
: LeftPistol
: LeftRifle
: Panic
: RightPistol
: RightRifle
: Sprint
|-
| <FirstLevel>
| int16
|Number of first level in which move becomes available to the player ("0" to make it available from the start).
|-
|valign="top"| <Shortcuts>
|valign="top"| parent tag
|
Works as an '''alternative FromState''' collection.

Shortcuts are accepted if their <Shortcut><FromState> value differs from the "primary" <Lookup><FromState> value. In other words, if you want to make a '''Shortcut''' that uses the '''same FromState''' value then you have to set '''primary FromState''' value to '''None'''. By doing that, the hardcoded interpolation frame length of about 8 frames can be overridden.

In the following example, the new interpolation length is 0. This will require the animation to match perfectly with the previous one. For a smooth transition to the next animation, set a suitable value at <Interpolation><End>.

<Lookup>
...
<FromState>None</FromState>
...
<Shortcuts>
<Shortcut>
<FromState>Standing</FromState>
<Length>0</Length>
<ReplaceAtomic>no</ReplaceAtomic>
</Shortcut>
</Shortcuts>

[[Image:TRAM interpolation - standard case.jpg|thumb|400px|left|Scenario A: hardcoded interpolation of 8 frames. Scenario B: changeable interpolation frame number.]]
|-
| <Shortcut>
| parent tag
|
|-
| <FromState>
| flag
| Look them up over [[XML:StNA#Animation_types|HERE]].
|-
|valign="top"| <Length>
|valign="top"| int16
|Amount of interpolating frames. While interpolations of rotation are less noticeable, interpolations of different positions can cause drift (i.e. sliding).

This is especially observed for transitions from idle to movements and vice versa — basically any combination of animations with different accelerations at start and end. By default, animations without specified Shortcut interpolation give about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

This drift can be observed even in vanilla animations — most prominently in Konoko's comb_k. Konoko's left foot should be in a fixed position as the animation starts from from Konoko's idle pose. However, the interpolation is causing her left foot to drift noticeably to the right and a bit forward.

The reason this happens is because the interpolation "mixes" two animations. When one animation transitions into another via interpolation, part of the animation system continues playing the initial animation, and part of it is playing the follow-up animation, with all the rotations and positions getting linearly interpolated.
|-
|valign="top"| <ReplaceAtomic>
|valign="top"| flag
|
: yes
: no
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are top-level flags on the whole animation. See the other <Flags> for flags on an attack part.
:RuntimeLoaded
::(This bit is not stored on disk; it is used at runtime to mark that the animation was loaded.)
:Invulnerable
::While playing this animation, the player is invulnerable to melee damage and also cannot be thrown. Damage from particles and fall damage still hurt.
:BlockHigh
::While playing this animation, the player is invulnerable to high or undefined attacks within some arc in front of him. If you set this flag on an animation where the player character is spinning, then the character can still be kicked in the back or thrown.
:BlockLow
::Same as above, only it can block low or undefined attacks.
:Attack
::Animations with an attack part have this turned on. It's unclear what it does, but it may enable the melee soft-lock (where the character turns a bit during the animation to face a nearby enemy).
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Something to do with jumps; not investigated.
:Atomic
::The whole animation must be played; player cannot interrupt it once it starts.
:NoTurn
:::Player cannot turn by mouse while performing this animation.
:AttackForward
::Unknown, but it looks like this is a hint for the AI about where an attack is aiming, from the player's point of view.
:AttackLeft
::Same as above.
:AttackRight
::Same as above.
:AttackBackward
::Same as above.
:Overlay
::Not a standalone animation; it just overwrites part of an already-playing one, e.g. the weapon-holstering animation.
:DontInterpolateVelocity
::Unknown, but maybe it has something to do with {x,y,z} velocities and the fact that directional jumps, for example, take information about their direction vector from the {x,z} velocity part of the TRAM (the vertical Y component is in the ONCC).
:ThrowSource
::Unknown, but throws use it.
::: Probably a developer relic. Throws work in animation pairs: whenever a throw source is played, the other character must perform the throw target animation. See throw(n) types:
:::: TRAM <TargetType>
:::: [[XML:StNA#Animation_types|StNA]] (First used throw starts at #96.)
::: Characters have only their own pool of animations available. And since enemy's TRAC might not contain the necessary animation the information must be provided by the throw source TRAC.
::: Since every throw animation must have a throw animation type the ThrowSource flag is actually redundant.
:ThrowTarget
::Animation can hurt anybody with its attack part, including teammates. The player can even hurt himself with the TRAM's damage part (whereas a player cannot hurt himself with his own animation's attack part). It also allows two attack parts to be executed instead of only one (maybe a bug? more than two will result in a crash).
:::If you set the first attack part to be able to deal damage from the 1st to the 100th frame of the TRAM, and the second attack part to deal damage within that range (e.g. from the 25th to the 41st frame), then the first attack part will deal damage from the 1st to the 100th frame (as usual), but even if it hits, that second attack part can hurt the enemy as well during frames 25–41. Note that the second attack part must be executed within the first attack part's active "window", otherwise it won't work.
:RealWorld
::It appears this flag was used to create a TRAM and an OBAN from one animation source. The OBAN is supposed to store pelvis rotations and positions, allowing a character to move over obstacles/gaps. The vast majority of them are used in cutscenes.
:DoAim
::Applies the aiming animation overlay (PIS/RIF) if the player has a weapon.
:DontAim
::An aiming overlay will not be applied.
:CanPickup
::Player can pick up an item during this animation if he intersects with one during his movement.
:Aim360
::Unknown.
:DisableShield
::If the player has an active supershield (chr_super "name" 1), this forces him to disable it (chr_super "name" 0)
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Makes animation particle atomic?
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage during a time frame defined by the Start and End frames.
|-
| <Start>
| int16
| First frame of character being invulnerable.
|-
| <End>
| int16
| Last frame of character being invulnerable.
|-
| <Overlay>
| parent tag
|
|-
|valign="top"| <UsedBones>
|valign="top"| flag
|Simply contains "<UsedBones />" if no bones are involved, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
|valign="top"| <ReplacedBones>
|valign="top"| flag
| "<ReplacedBones />" if unused, otherwise:
:Pelvis
:LeftThigh
:LeftCalf
:LeftFoot
:RightThigh
:RightCalf
:RightFoot
:Mid
:Chest
:Neck
:Head
:LeftShoulder
:LeftArm
:LeftWrist
:LeftFist
:RightShoulder
:RightArm
:RightFist
|-
| <DirectAnimations>
| parent tag
|
|-
| <Link>
| link
| First slot. "<Link />" if unused.
|-
| <Link>
| link
| Second slot. "<Link />" if unused.
|-
| <Pause>
| parent tag
|
|-
| <Hard>
| int16
| In ticks. The Hard and Soft pause values are ignored if this animation has a direct link (above) to another animation.
|-
|valign="top"| <Soft>
|valign="top"| int16
| In ticks. As mentioned above, the player cannot enter new inputs during this pause unless this animation is part of a combo animation defined by <DirectAnimations><Link>.
: Examples:
: COMcomb_p, (no pause) COMcomb_p_p
: COMcomb_p, (pause) COMcomb_k

The difference between the hard and soft pause is that you can block during the soft pause and not the hard pause.
|-
| <Interpolation>
| parent tag
|
|-
|valign="top"| <End>
|valign="top"| int16
|
* interpolates first X frames of next animation
* if the first follow-up animation is too short, it can continue to play even further (not observed with vanilla anims)

While interpolations with rotations are less noticeable, interpolations of different positions can cause an additional drift.

This was especially observed for transitions of idle to movements and vice versa — basically any combination of animations with different accelerations at the start and end. By default, animations without a specified Shortcut interpolation get about 8 frames of interpolation. For moves starting or ending in idle, it's better not to use interpolation. Just give the start and end frames the same positions and rotation values as the idle. Interpolations should always be considered a ''last resort''.

[[Image:TRAM interpolations - end interpolation bigger than next anim.jpg|thumb|400px|left|"End" interpolation covering multiple follow-up animations.]]
|-
| <Max>
| int16
| unused
|-
|valign="top"| <FinalRotation>
|valign="top"| float
|valign="top"| Ending rotation in degrees. (During an animation, the camera is detached rotation-wise. If this value matches the body's final rotation, it will prevent a "glitchy" re-attaching.)
|-
|valign="top"| <Direction>
|valign="top"|
| Used by [[AI#Melee_combat_behaviors|AI melee system]].
:None
:Forward
:Backward
:Left
:Right
|-
| <Vocalization>
| int
| ID of one of the [[XML:SNDD#Step_1:_Preparing_the_TRAM|SoundConstants in ONCC]]
|-
| <ActionFrame>
| int
| Frame number for any special events associated with this animation: weapon theft via disarm, weapon holstering, Mukade teleporting, items getting handed over to player, etc.
|-
| <Impact>
| link
| "<Impact />" if unused.
|-
|valign="top"| <Particles>
|valign="top"| parent tag
| serves as group element
|-
|valign="top"| <Particle>
|valign="top"| parent tag
| holds individual particle data
|-
|valign="top"| <Start>
|valign="top"| int
| frame number for particle to start
|-
|valign="top"| <End>
|valign="top"| int
| frame number for particle to end (if the number exceeds frame count of animation, the particle will simply die at the end of the animation)
|-
|valign="top"| <Bone>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
|valign="top"| <Name>
|valign="top"| link
| particle name in [[XML:ONCC#ONCP:_Oni_Character_Particle_.28Array.29|ONCC-ONCP]]
|-
| <MotionBlur>
| parent tag
|
|-
| <MotionBlur>
| parent tag
| sequence element
|-
|valign="top"| <Bones>
|valign="top"| flag
|
: Pelvis
: LeftThigh
: LeftCalf
: LeftFoot
: RightThigh
: RightCalf
: RightFoot
: Mid
: Chest
: Neck
: Head
: LeftShoulder
: LeftArm
: LeftWrist
: LeftFist
: RightShoulder
: RightArm
: RightFist
|-
| <Start>
| int16
| Start frame of motion blur sequence
|-
| <End>
| int16
| End frame of motion blur sequence
|-
| <Lifetime>
| int8
| Lifetime of each "ghost" in frames.
|-
| <Alpha>
| int8
| Transparency of "ghosts".
|-
| <Interval>
| int8
| Frame interval between each rendered "ghost".
|-
| <Footsteps>
| parent tag
|
|-
| <Footstep>
| parent tag
|
|-
| <Frame>
| int16
|
|-
|valign="top"| <Type>
|valign="top"| flag
|
: Left
: Right
|-
| <Sounds>
| parent tag
| "<Sounds />" if unused.
|-
| <Sound>
| parent tag
|
|-
| <Name>
| char[32]
| OSBDfile.imp.oni (don't use resource type's prefix or suffix)
|-
| <Start>
| int16
|The frame when the sound starts to play.
|-
| <Heights>
| parent tag
|
|-
| <Height>
| float
|Absolute position.
|-
| <Velocities>
| parent tag
|
|-
| <Velocity>
| 2 x float
|Relative positions (delta values); the numbers represent the change in position from one frame to another.
|-
| <Rotations>
| parent tag
|
|-
| <Bone>
| parent tag
|There are 19 bone tags, one for each [[TRIA#Bones|body part]].
|-
| <EKey>
| int8 + 3 * float
|For normal animations. The first value is the number of frames for which the rotation is maintained; the sum of all of these first EKey components always equals the total number of frames for the animation.
|-
|valign="top"| <QKey>
|valign="top"| int8 + 4 * float
|For overlay animations used by [[TRAS|TRAS]] aiming screens.

OniSplit v0.9.54.0 produces <QKey>s (quaternions) instead of <EKey>s (Euler rotations) for normal animations.
|-
| <PositionOffset>
| parent tag
| <PositionOffset> and <Positions> belong together. In the [[OBD:TRAM/raw0x30|binaries]], they are written in place. '''Seems unused; changing them has no effect in-game.'''
|-
| <X>
| int16
|
|-
| <Z>
| int16
|
|-
| <Positions>
| parent tag
|
|-
| <Position>
| float
| seems to be unused (and when checking this with "chr_debug_sphere = 1", the spheres remain unchanged)
|-
| <Height>
| float
| vertical extent
|-
| <YOffset>
| float
| Y offset of the vertical extent from character location
|-
| <ThrowSource>
| parent tag
| "<ThrowSource />" if unused.
|-
| <TargetAdjustment>
| parent tag
| Used to position targets during throws, relative to the position of the character executing the throw.
|-
|valign="top"| <Position>
|valign="top"| 3 * float
| Contains XYZ values, which position the target character:
*X - Side axis. Negative values move the target to the right and positive values move the target to the left.
*Y - Height axis. Negative values move the target downwards, but cannot make the target go below the floor. Positive values make the target go upwards — if the value is too big, the target will teleport upward and then immediately start falling, interrupting the target animation.
*Z - Forward axis. Negative values move the target backwards and positive values move the target forward.
|-
| <Angle>
| float
| In radians - adjusts the rotation of the target in Oni's Y axis; most of the time (if not always) it's set to ''3.14159274'' radians in vanilla anims, equaling 180 degrees - which effectively rotates the rotates by those 180 degrees; if it was set to 0, the target would face the throw source character with his back.
|-
| <Distance>
| float
| Activation distance. The throw can be triggered if it is within this range. However the value must be greater than the equivalent TRAM in the parent TRAC.
|-
|valign="top"| <TargetType>
|valign="top"| flag
| The flags are part of the [[XML:StNA#Animation_types|animation type list]].

(static throws)
: Thrown1 = ###COMthrow_fw_p_tgt
: Thrown2 = ###COMthrow_fw_k_tgt
: Thrown3 = ###COMthrow_bk_p_tgt
: Thrown4 = ###COMthrow_bk_k_tgt
(running throws)
: Thrown5 = ###COMrun_throw_fw_p_tgt
: Thrown6 = ###COMrun_throw_fw_p_tgt
: Thrown7 = ###COMrun_throw_bk_k_tgt
: Thrown8 = ###COMrun_throw_bk_k_tgt (not tested)
(tackle throw = catching)
: Thrown9 = ###COMrun_tkl_fw_p_tgt (not tested)
: Thrown10 = ###COMrun_tkl_bk_p_tgt
(pistol disarms)
: Thrown11 = ###PISthrow_fw_p_tgt
: Thrown12 = ###PISthrow_fw_k_tgt
: Thrown13 = ###PISthrow_bk_p_tgt
(rifle disarm)
: Thrown14 = ###PISthrow_bk_k_tgt (not tested)
: Thrown15 = ###RIFthrow_fw_p_tgt
: Thrown16 = ###RIFthrow_bk_p_tgt
: Thrown17 = ###RIF? = (not tested)
----
About the naming:
: "fw" = face-to-face throw
: "bk" = thrower is facing victim's back
: "throw" inside TRAM names is sometimes shortened to "thr"
: "p"/"k" = triggered by punch or kick button ("p" is sometimes omitted)
|-
| <SelfDamage>
| parent tag
|"<SelfDamage />" if unused.

Works only with specific, hardcoded AnimTypes (mainly ThrownX, it's unknown if any other types work - that remains to be investigated). Using SelfDamage on an AnimType that wasn't intended for it will cause the game to crash. (ToDo: Checked if <Flag>ThrowTarget is enough to explain this. Modify a simple kick? For more please link to and use talk page.)

From a practical standpoint, this means SelfDamage can be used only on ThrowTarget animations.
|-
| <Damage>
| parent tag
| sequence element
|-
| <Points>
| int16
| Damage taken by character.
|-
| <Frame>
| int16
| Frame of the animation when damage is dealt.
|-
| <Attacks>
| parent tag
|
|-
|valign="top"| <Attack>
|valign="top"| parent tag
| Only 2 attack parts per file are allowed. Normally the target gets only one hit. But if the attack frame ranges of both attack parts are overlapping, then the target can be [http://oni.bungie.org/forum/viewtopic.php?pid=39787#p39787 hit by both of them].
|-
| <Start>
| int16
| First frame where damage can be inflicted on an opponent.
|-
| <End>
| int16
| Last frame where damage can be inflicted on an opponent.
|-
| <Bones>
| flag
| The bones which can inflict damage.
|-
|valign="top"| <Flags>
|valign="top"| flag
|These are flags on an attack part, inside an <Attacks><Attack> element. See the previous <Flags> for general flags on the TRAM.
: Unblockable
: Low - Target of attack needs to crouch in order to block this attack.
: High - Blocker needs to stand; if both Low and High are set, blocker can block from both standing and crouching positions.
: HalfDamage - Blocker receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount.
|-
| <HitPoints>
| int16
| Damage points inflicted by attack.
|-
| <HitType>
| flag
| Animation type for opponent's animation when the attack isn't blocked. The flags are part of the [[XML:StNA#Animation_types|animation type list]].
|-
| <HitLength>
| int16
| Number of frames that the target should remain in his hit animation state when he gets hit.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack.
|-
| <StaggerLength>
| int16
| Number of frames that the target should perform his stagger animation after a successful block.
|-
| <Extents>
| parent tag
| Explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML.
|-
| <Extent>
| parent tag
| One tag per attack frame. Number of <Extent> tags = <Attack><End> - <Attack><Start> + 1
|-
| <Angle>
| float
| In degrees.
|-
| <Length>
| float
|
|-
| <MinY>
| float
|
|-
| <MaxY>
| float
|
|-
|valign="top"| <AttackRing>
|valign="top"| parent tag
| Always contains 36 <Length> tags, explained below. Automatically calculated by OniSplit if there's a DAE file referenced in the XML. (AttackRing was formerly known as "horizontal extents" in older versions of OniSplit.)
|-
|valign="top"| <Length>
|valign="top"| float
| Horizontal extents, explained below. They create a "danger zone" around the attacker which the AI uses to try to dodge an attack.
|}

==Export==
TRAM files can be extracted '''A) as pure XML''' files or '''B) as a pair of XML and DAE''' files. For editing the actual animation, you will want to use method B. While exporting an ONCC, you might see errors such as:

Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONCOMthrow_rev'
Cannot find instance 'TRAMKONRIFturn_right'
Cannot find instance 'TRAMKONOKOlev18_ZomStand'
Cannot find instance 'TRAMKONOKOcorner_hide'
Cannot find instance 'TRAMKONPIScorner_hide'

Ignore them, as those files doesn't exist. (Someday we should remove them from the TRACs.)

===Via command line===
To export a single TRAM:
onisplit -extract:xml output_path -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname.oni

To export merged TRAMs:
onisplit -extract:xml output_path '''-anim-merge''' -anim-body:path_to\TRBS_or_ONCCname.oni path_to\TRAMname1.oni path_to\TRAMnameN.oni

===Via Vago===
[[Image:Vago_xml_plus_dae_extraction.png|thumb|200px|right|Combined extraction of DAE and XML.]]

Change to Characters tab and follow these steps.

'''Step 1:''' Select "TRAM ONI" as input format ("From").

'''Step 2:''' Select "XML / XML & DAE" as output format ("To").

'''Step 3:''' Tick checkbox "Extract with TRBS / ONCC". It's important this is done before adding a TRAM file.

'''Step 4:''' Set full path of ONCC or TRBS.

'''Step 5:''' Add TRAM file.

'''Step 6:''' Click "Convert".

===Via Simple OniSplit GUI===
There was a long-standing problem with combined ONCC/TRAM files where the textures would be missing.

'''[http://www.paradox.oni2.net/programs/Simple_OniSplit_GUI.zip Simple OniSplit GUI]''' post-edits the DAE to fix missing textures. The character-related .oni files must be all in one folder. Usually the level0_Final folder does the trick.

'''Step 1:''' Drag and drop the TRAM and ONCC into the [http://www.paradox.oni2.net/images/simpleOniSplitGui.png big field.] (One by one or simultaneously; the order doesn't matter.)

'''Step 2:''' Hit "Convert".

==Editing 3D data==
===Blender===
See the [[Blender]] article for a general tutorial on using the free program to create animations for Oni. It also contains code snippets for automating certain tasks, troubleshooting advice, and links to an IK rig that makes animation much easier.

===XSI===
In the past, the community's preferred tool for any 3D modeling and animation was {{ModTool}}. However, this free program was discontinued in 2014, and modders did not want to be tied to an aging (not to mention Windows-only) program. Thus, we have generally moved to using Blender (see next section). The following information is preserved for historical purposes.
----
For the correct Mod Tool settings, see [[Mod Tool#Animating|HERE]].

Here are some hints for creating animations when there is no rigging available:
* Use the ONCC model in your 3D editor that will actually make use of the animations. This makes sure that the pelvis height will match and that the character's feet will not float in the air or go through the ground.
* The first frame and last frames should match the probable previous and follow-up animations. This will reduce the necessity for long interpolations.
* When setting keyframes, each body part should have moved. This rule of thumb will give a more natural-looking animation.
* The first body part to be animated is always the pelvis.
* Watch out for pelvis rotations so that the XYZ rotations don't overlap too much, otherwise you will get into a [[wp:Gimbal_lock|gimbal lock]].

Also see our [http://oni.bungie.org/forum/viewtopic.php?id=1433 OCF thread].

==Import==
onisplit -create output_path path_to\TRAMname.xml

==Common operations on animations by the community==
===Speeding up existing animations===
s10k has created an XmlTools script that allows the speed-up of any existing TRAM by removing frames. More information and download link [http://mods.oni2.net/node/354 here.]

==Selected notes on animation types==
===Attacks===
====Extents and XML====
'''As a regular modder you don't need to know how the attack ring and the extents get calculated.''' If you just want to create an attack animation then add an appropriate <Attacks> code block to your XML as seen in the [[#Using OniSplit to calculate extents|section below]].

'''How attack ring (horizontal extents) and extents get calculated'''

Ever wondered how the AI can recognize incoming attacks and block or dodge them? Extents (found by geyser and fully uncovered by Neo) are the key. Imagine the character looked at from above, and visualize a circle with this character being at the center of the circle. Now divide this circle into 10° segments, and those are the 36 units of horizontal extents (that is, the lateral reach of the attack). The 0° point is directly in front of the character and 180° is behind the character. The segments run clockwise around the character. So the first Extent tag is the horizontal reach on the 0° line, the second tag is for the line 10° clockwise, and so on. Note that a frontal attack like a simple kick could hit a target not only if he's standing at 0° (directly in front), but also at 10° or 20° to the right, and also at 340° and 350° (a bit to the left). When setting these manually, you should guess the inner and outer ranges of the reach of the attacker's bones that have damage attached to them. Test these values with an AI that blocks often. If you did it right, your attack will often be blocked, but if the extent length is too high, the AIs will react when too far from you, which does not look good.

There are two types of extents:
*'''<Extents>''' stores this info:
::<Angle> at which this extent radiates from the character.
::<Length> of this extent.
::<MinY> minimum height of this extent.
::<MaxY> maximum height of this extent.
:Length, MinY and MaxY serve to create an invisible area in space which is "dangerous to be in". If an AI intersects with this area and notices it (refer to the Notice field in [[MELE]]), it will attempt to block or dodge according to its modifiers in its MELE profile.
::The number of <Extent>s is equal to the number of attack frames: <End> minus <Start> plus one (because the start frame counts too). For example, for TRAMKONCOMkick_low1: <End>30</End> minus <Start>22</Start> plus 1 = 9 <Extent>s.

*'''<AttackRing> (formerly known as <HorizontalExtents>''' stores this info:
::36 fields (exactly 36, otherwise it won't compile back into a .oni file), which correspond to areas in 10° intervals around the character as described above.

====Using OniSplit to calculate extents====
Let's say that you want to convert a non-attack animation to a damage-dealing animation. Non-attack TRAMs do not have extents information used to notify the AIs about incoming attacks, so how do you generate this information from the animation?
:1. Export the animation to XML with a body attached. If you extract using just "-extract:xml dest_folder TRAMsomething.oni", you'll get the 3D animation data inside the XML (namely, the tags Heights, Velocities, Rotations, PositionOffset, and Positions; for an attack animation, you'll also get Attacks and AttackRing, and inside Attacks' elements, each Attack element will have Extents at the end of it).
:However, if you extract this same animation using "-extract:xml dest_folder TRAMsomething.oni '''-anim-body ONCCtramuser.oni'''", the animation data will be placed in a DAE file along with the character model geometry. Be sure to pick a body with a size that's representative of the character classes that will actually use this TRAM, because the extents will be calculated from it. The XML file will be very short without the 3D data in it — this is how we want the non-attack TRAM to look. We do not know the extents information that should go in Extents or AttackRing, so we just want to add the part that distinguishes a DAE-extracted attack TRAM XML from a DAE-extracted non-attack TRAM XML. That part is the Attacks section, without the Extents under each Attack.
:2. First, consider whether the TRAM should have something added to its Flags section, like Attack or ThrowTarget.
:3. Now add to the XML of the non-attack TRAM data in the following format (after the <SelfDamage /> section, typically):
<Attacks>
<Attack>
<Start>1</Start>
<End>10</End>
<Bones>RightWrist RightFist</Bones>
<Flags />
<Knockback>4</Knockback>
<HitPoints>10</HitPoints>
<HitType>KnockdownHead</HitType>
<HitLength>5</HitLength>
<StunLength>8</StunLength>
<StaggerLength>0</StaggerLength>
</Attack>
</Attacks>
:Do not add an AttackRing section after Attacks.
:4. Import this with "-create dest_folder TRAMsomething.xml". The Extents sections and the AttackRing will be calculated by OniSplit from the attached DAE.
:5. If you need this information for a patch mod, run "-extract:xml" on the TRAMsomething.oni you've created without using "-anim-body". Now you can copy the Extents and AttackRing data to your XML patch. For an example of how the patch should look, see the [http://mods.oni2.net/node/311 Domino Knockdowns] mod.

===Combos===
The type and order of player input for triggering a given animation type (such as PPK) is hardcoded, and new animation types cannot be created. To assign an animation type to a specific combo attack, you set a corresponding value in <Lookup><Type>.

Setting a value in the <Link> of '''<DirectAnimations>''' will do two things:
# It will increase the time window for player input, meaning the next animation can be executed more easily. (In vanilla Oni, the Crescent Moon Kick has no link in KONCOMcomb_k_k_kfw and therefore is difficult to use.)
# It disables <Interpolation><End> for the next combo anim.
# It enables <Pause><Soft> and <Pause><Hard>.

===Just Frame input===
Implemented by Delano762, inspired by the game series Tekken, a Just Frame ("JF") move means that you have to press certain keys (W+K or W+P) at the exact same time, which is more difficult than it might sound. Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko] has a collection of animations which utilize existing animation states differently to create new moves.

Example 1:
* new forward kick = TRAMKONCOMkick_fw_JF <FromState>Standing
** key strokes: w + k
* old forward kick = TRAMKONCOMkick_fw <FromState>RunStart
** key strokes: w, k

Example 2:
* new forward punch = TRAMKONCOMpunch_fw_JF <FromState>Standing
** key strokes: w + p
* old forward punch = TRAMKONCOMpunch_fw <FromState>RunStart
** key strokes: w, p

Note that these animations are referred to as JF moves, not JF combos. The Crescent Moon Kick, as mentioned above, is an unintentional JF combo found in vanilla Oni.

===Throws===
: Todo: Add here throw pair table from talk page when it is complete.

Throw target animations are registered in the TRAC of the throw initiator (AKA the throw source). Target animations are forced onto the other character, removing the need to have that animation in the target's TRAC. Throw target (TRAM*tgt) animations can only cover up to 256 frames (0-255).

====Forward throws====
Scenario: You load two characters into Mod Tool and rotate (+/-180°) the throw target character because you need them to stand face to face as you work on an animation. When you are done animating, the target animation would need to be reversed again. This means multiplying the velocities by -1; the rotation also needs correcting. So it looks like you need *(-1) for the x rotation and -/+180° (depending on your initial change) for the Y rotation.

=====BlenderOni Throw Adjust=====
There is a Blender script implemented within the BlenderOni addon for rotating and adding PositionOffset to a forward throw Target animation. It is capable of adjusting both forward and back throws. The script's old version can be accessed [[Blender/Obsolete_scripts#Script_for_adjusting_forward_throw_targets|HERE.]]

====Excel macro====
[[Image:Animation_macro_v4.png|right|thumb]]
The Excel macro can be used to create any TRAM except overlays. [https://www.youtube.com/watch?v=vDTPYfvMf4M Demo vid here].

The macro should be rewritten as a .NET framework or application because Excel is not freeware. However, the tool was made with XSI in mind (for getting animation pair-based information). As XSI is mostly considered obsolete by the community, research for doing the same with Blender will be needed.

There was some development of a .NET-based '''[[TRAM setup assistant]]''' in 2016, but the work drifted into inactivity since the community showed no sign of demand for an updated tool.

As of now there is a Blender script for creating throw target adjustment data. So instead of writing a new stand-alone app, at least the creation of header data might be better ported to the Blender script.

'''Macro usage:'''
* Put your files into the "input_and_output" folder.
* Disable macro security if you don't want to have to click on the "Enable Content" button every time.
* Close other worksheets before you run the macro.
* If you are not afraid of VBA code, you can enter the dev environment by hitting Alt+F11. If you want to extend the attack library with more screenshots and settings, search for "LibraryThrows", "LibraryAttack", "Picture", and "CBAttackHelp.AddItem".

===Run animations===
Here's a breakdown of the Striker's run animations, meant as an illustration for what would be needed to make new run TRAMs.

Run cancel:
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErun1stepb
* STRIKEidle1 / another idle animation

Run – ''a minimal cycle'':
* STRIKEidle1 / another idle animation
* STRIKErun1stepa
* STRIKErunstart
* STRIKErun_rt
* STRIKErun_lt (optional)
* STRIKErunstop
* STRIKEidle1 / another idle animation

Follow the images below from right to left.
<gallery>
Image:XML_TRAM_STRIKErunstop.png|STRIKErunstop
Image:XML_TRAM_STRIKErun_lt.png|STRIKErun_lt
Image:XML_TRAM_STRIKErun_rt.png|STRIKErun_rt
Image:XML_TRAM_STRIKErunstart.png|STRIKErunstart
Image:XML_TRAM_STRIKErun1stepa.png|STRIKErun1stepa
</gallery>

==List of unused animations==
Here are all the known unused animations. These could be recycled in a new mod.

'''From the original game'''
* KONOKOconsole_punch: What the name says (the engine can use that animation depending on the console's configuration, see [[OBD:BINA/OBJC/CONS|CONS]]) .
* KONOKOlev3_intro: Looks like she's placing something (bomb?) and then running away.
* KONOKOlev4_undress: From an aborted clothes-changing cutscene.
* KONOKOlev16_bomb: Planting a bomb.
* KONCOMsuper_kick: Now used in [[OTA]] as a spawn event, and by the fan-made character [[Shinatama Evolved]].
* KONCOMsuper_punch: KONCOMpunch_heavy but without the shouted attack name, has HalfDamage flag, and does 10 less damage in its first attack part.
* COMPISidle_special1: Comguy checking environment and his gun; meant for a feature that would visually depict an elevation in the AI's level of alertness after, say, hearing a noise.
* STRPISidle_special1: Striker checking his his gun and communicating with an ally (another unused alertness-elevation animation).
* THUGlev1_direct: Thug probably directing a truck driver.

'''From modders'''

[[Image:female_stun.jpg|right|thumb|Char A and Char B performing stun animations.]]

* http://mods.oni2.net/node/376
** StrikerKneeStepKickThrow.zip
** REDCOMjump_fw_crouch--double_flip--dae.zip
** KONprone_getup--dae.zip
** KONRIF_k_bk_throw.zip
** female_stun--dae.zip

==Special effects==
If the scene is overloaded by too many particles (including motion blur), these effects will cease being rendered. So don't overuse effects.

===Color trails===
Open the XML-accompanied TRAM, search for the "Particles" tag, and insert your markup.

First example: TRAMSTRCOMcomb_p_p.xml

[[Image:Colorful_contrail_added.png|right|thumb]]

<Particles>
<Particle>
<StartFrame>0</StartFrame>
<EndFrame>12</EndFrame>
<Bone>LeftFist</Bone>
<Name>contrail</Name>
</Particle>
</Particles>

"contrail" is looked up by the character class (ONCC) that emits the actual particle; here it is "h2h_strtrail_e01".

This second example is about creating two different contrails in a TRAM at the same time. The animation is "TRAMSTRCOMpunch_heavy.xml".

[[Image:Different_contrails_in_attack.png|right|thumb]]

<Particles>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>RightWrist</Bone>
<Name>contrail</Name>
</Particle>
<Particle>
<Start>0</Start>
<End>54</End>
<Bone>LeftWrist</Bone>
<Name>'''contrail_2'''</Name>
</Particle>
</Particles>

Note that you need to register the second contrail in the ONCC as well. Using your own contrail particle is also possible; just insert its name between the <Type> tags.

<ONCPParticle>
<Name>contrail</Name>
<Type>h2h_strtrail_e01</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>
<ONCPParticle>
<Name>'''contrail_2'''</Name>
<Type>'''h2h_murtrail_e01'''</Type>
<BodyPart>-1</BodyPart>
</ONCPParticle>

===Motion blur===
[[Image:XML_TRAM_willow_kick_with_motion_blur.jpg|thumb|200px]]

===Impact effect===
[[Image:XML_TRAM_KONCOMkick_fw_with_ninflash1.jpg|thumb|200px]]

See also [[XML:ONCC]].

{{XML}}

Importing character models

2022-11-21T10:39:17Z

Delano762: /* Blender-specific OniSplit information - minor adjustments */

This article covers the importing of new character models into Oni, but also how to export models from Oni. Generally speaking, you are going to want to use [[wikipedia:COLLADA|COLLADA]] as the "passthrough" format between your 3D program and Oni, as this is exactly what COLLADA was designed for. In this article, COLLADA is referred to as "Collada" (because who enjoys being shouted at?), or by ".dae file" (because that is the file suffix for COLLADA).

==Modding tools==
===OniSplit===
This is the program that we use to get models into and out of Oni. It is a command line tool. There are GUI wrappers for OniSplit that cover most of its functions (see [[Vago (tool)]], but modders sometimes have to call it from the command line (or use the direct command line input feature in a GUI) to take full advantage of OniSplit's abilities.

===3D programs===
====Blender====
[[Blender]] is the community's current 3D software of choice, allowing for 3D modeling, animating, and more.

Blender rocks when it comes to [[Lightmapping levels|lightmapping levels]]. 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]]).

====XSI====
Softimage XSI is a Windows-only 3D software that went discontinued in 2014, and [https://www.moddb.com/downloads/autodesk-softimage-mod-tool-75 a free version of it from 2008] used to to be the community's modding tool of choice before moving on to Blender. A number of Oni-related addons, tools and tutorials were developed for it can be still found and used. It has detailed documentation and is versatile, whether working with characters or levels, though highly obsolete.

===File converters===
====Autodesk FBX====
Check out {{AutodeskFBX}} (primarily the FBX converter) if your tool can reliably import/export FBX but has trouble with Collada.

==Basic importing and exporting==
===Exporting from Oni to Collada===
OniSplit allows you to export .dae files from both [[TRBS]] and [[ONCC]]. Though all the 3D data is in the TRBS, the textures are listed in the [[TRMA]] file, which is only visible from the ONCC, not the TRBS. Thus, if you want to use the textures while editing the model, convert the ONCC, not the TRBS, into Collada. The instructions below assume that you want the textured model, and thus illustrate how to export the ONCC.

First, you need to find the class name for the character you want to export. You can accomplish this by going into Oni, loading the level in which the desired character appears, and then enabling the shapeshifter cheat -- but you have to do this by turning on [[Developer Mode]], not by entering the "shapeshifter" cheat code, because the regular cheat code does not display the console output that you need. Once Dev Mode is on, press F8 until you reach the desired character. You should see the message "character class ''number'' '''''string'''''". The number is unimportant, but write down the string, because that is the class name which provides the basis for the names of the ONCC and TRBS.

In this example, we'll export one of Konoko's models. For Konoko, we don't even need to open Oni to find the name of an ONCC because we have [[Konoko#In-game_outfits|this handy table]]. Let's use Konoko in her police uniform; you can see from the table that this is ONCCk3 and that it's found in level2_Final.

Next, you need to decide on the pose in which your character will be exported. See the "Poses" section below for guidance. Without making this example more complicated, we only have two choices for pose: default (folded) and -noanim (standing at attention); we are going to use the second option, for a more visually pleasing result. Here are the steps for getting your desired character in .dae format. Substitute backward slashes for forward ones if you are in Windows.

:1. Create a couple of folders in a convenient place. One folder will receive a whole bunch of files, and the second folder will hold the exported model. We'll call these paths "splitOutput/" and "modelOutput/" respectively.
:2. On the command line, go to the directory "Oni/GameDataFolder/", where "Oni/" means the path to your game.
:3. Split the desired level's data into its component resources with OniSplit. Where you see just "onisplit" in the following commands, you should take that to mean "C:\path\to\OniSplit.exe" in Windows or "mono /path/to/OniSplit.exe" on Macs (Mono is a third-party package that you need to run .NET applications in macOS):
::<tt>onisplit -export splitOutput/ level2_Final.dat</tt>
:4. Convert the desired character's model data into Collada:
::<tt>onisplit -extract:dae modelOutput/ -noanim splitOutput/ONCCk3.oni</tt>

This will create the file '''ONCCk3.dae''', and its supporting textures in TGA format, in modelOutput/. Note that only the highest level of detail (LOD) model will be exported using this method. See [[XML:TRBS]] for a method which exports all 5 LOD models.

Note that if you want to extract the model with a pose besides folded or -noanim, you need to have the animation data (the [[TRAC]] and [[TRAM]] .oni files) in the same folder as the model data (the ONCC and its related files). In vanilla (un-modded) Oni, animations for many characters (including Konoko) are only in level0_Final, and, as you saw above, model data is found in whichever level that character appears in. Extracting a model in the pose of your choice will be simpler if you have the [[AE]] installed, as it globalizes character data, placing it all in the level0_Final files in the AE's GameDataFolder. With vanilla Oni, you will have to split both level0_Final and level''x''_Final and then combine their files into one folder before you can perform the "-extract:dae" operation using the "-anim" tag that is discussed below.

===Importing from Collada into Oni===
When importing characters, the simplest method is to generate a whole body set ([[TRBS]]) from one .dae file. To convert your 3D model, let's say that you saved it in Collada format with the name "TRBSnewchar.dae". Run the command:
:<tt>onisplit -create:trbs DAEtoONI/ TRBSnewchar.dae</tt>

This will create '''TRBSnewchar.oni''' in the folder DAEtoONI. Because it was created from a single .dae file, this TRBS will contain 5 identical models for the 5 levels of detail (LOD) that Oni supports for each character. You have to import by XML in order to specify a different .dae for every LOD; see [[XML:TRBS]] for more info.

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 if you were editing a model exported from Oni). Possibly a future version of OniSplit can automatically generate a TRMA and TXMPs if the .dae file has textures.

Note that your file should be named appropriately if you want it to be looked up by name from one or more of Oni's existing ONCCs, or a new one of your own creation.

To actually test the model in-game, you should [[Making a mod package|create a mod package]] for it, place the package in Oni/AE/packages/, and select it in the AE Installer. The older method of testing your work is to rebuild the level by running "onisplit -import" on a folder containing your TRBS and all the other .oni files for a level, but this only creates a set of level files that you can use on your computer, and is inherently a disorganized approach to keeping track of your work. Creating an AE package will allow you to share your work with other players.

Please note that a final character mod package should contain multiple LOD models for your character. Filling all 5 slots with distinct models is not necessary; many modders create only two or three LOD models and fill the lower LOD slots with the simpler model(s) and the highest slot with the full-detail model, e.g.:
:# TRBSnewchar_low.dae
:# TRBSnewchar_low.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_high.dae

An ONCC contains much more information than just links to TRBS and TRMA, and thus can not be generated automatically. See [[XML:ONCC]] on how to create such a file, and then import the character with this class data into Oni. The easiest way to try out an imported character in Oni is to name your imported TRBS so that it replaces an existing one and no ONCC editing is needed. The next step up is to clone an existing ONCC (in XML) and modify it to link to your new TRBS file(s).

==Blender-specific OniSplit information==
This section contains OniSplit commands specific to Blender, and related settings in Blender necessary for assets to work.

===Blender settings for importing and exporting COLLADA files===
====Importing====
In the Collada Import Data Options, make sure to check Import Units. Failure to do so will result in scaling issues, which are not easy to fix.

Before importing TRAM files, set the scene frame rate to 60 FPS. Failure to do so will result in keyframes being placed incorrectly on the timeline.

{| class="wikitable"
|-
! Collada import settings !! Scene settings
|-
| [[Image:BlenderImportSettings.png|200px|frameless|center]] || [[Image:BlenderSceneSettings.png|300px|frameless|center]]
|-
|}
====Exporting====
When exporting TRBS, be sure to delete the default light and camera from the scene, or you can select all 19 body parts, then in the Export Main Tab, select Selection Only.

When exporting TRAM, select all 19 body parts, then in the Collada export options, under the Main Tab: select Selection Only, Geom Tab: select Triangulate, Anim Tab: select Curves.

{| class="wikitable"
|-
! Blender Collada export settings
|-
| [[Image:BlenderColladaExportSettings.png|500px|frameless|center]]
|-
|}

===Blender-specific OniSplit commands===
*Convert TRBS.oni to Blender compatible dae:
-extract:'''dae''' To_blender -noanim -blender Original\TRBSkonoko_body_high.oni

*Convert ONCC.oni to Blender compatible dae with textures:

-extract:'''dae''' To_blender -noanim -blender Original\ONCCkonoko_generic.oni

Be sure to include the TMXP.oni files with the ONCC.oni file.

*Convert TRAM.oni to Blender compatible dae - '''textureless''', as exporting animations with textured models does not work yet:

-extract:'''xml''' To_blender -anim-body:Original\TRBSkonoko_body_high.oni -blender Original\TRAMKONCOMkick_heavy.oni

This will create a TRAM.dae along with an .xml file, which is needed for importing back to Oni. You will be also able to tell that everything went okay when you see
<tt>AnimationDaeWriter: custom axis conversion</tt>
on output. If you don’t, you’re most likely doing something wrong.

*Convert TRBS.dae from Blender to .oni:
-create:'''trbs''' From_blender -blender From_blender\TRBSkonoko_body_high.dae

*Convert TRAM.dae from Blender to .oni
-create From_blender -blender From_blender\TRAMKONCOMkick_heavy.xml
The TRAMKONCOMkick_heavy.xml links to the TRAMKONCOMkick_heavy.dae from Blender which needs to be in the same location as the .xml file.

===Troubleshooting===

Known Issues between Blender 2.83 and OniSplit 0.9.99.2:

1) Importing a .dae file results in the following error message:
"Schema validation (Error): Error: ERROR_REQUIRED_ATTRIBUTE_MISSING Element: technique, Attribute: sid"

Solution: Open the .dae file in a text editor, find all instances of <tt><technique></tt> and replace with <tt><technique sid="common"></tt>

==Poses==
===Oni's default orientation===
This pose, where the body parts are all at zero rotation, is usually referred to in the community as the "folded pose". 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, in the default pose, you can see the "true" translations (offsets) 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===
[[Image:Konoko_bodyparts.png|thumbnail|right|283px]]
Supplying the '''-noanim''' switch to OniSplit yields the "standing at attention" pose, a much less visually awkward pose than the default "folded pose". Note that "-noanim" goes in between the destination directory and the source file name:
:'''onisplit -extract:dae modelOutput/ -noanim ONCCkonoko_generic.oni'''

The result will look something the picture on the right, but the model will have her legs together and her arms by her side.

To produce this pose, these rotations are used:
:(0,90,90) for the pelvis
:(0,180,0) for both thighs
:(90,90,90) for the left shoulder
:(-90,-90,90) for the right shoulder
:(0,90,0) for the left biceps
:(0,-90,0) for the right biceps
:(-90,0,0) for the left hand/fist
:(90,0,0) for the right hand/fist
:(0,0,0) for all other parts
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.

===Idle pose===
If you use '''-extract:dae TargetFolder ONCCkonoko_generic.oni''', taking care that you have the TRAC/TRAM files next to the ONCC, OniSplit will look up the idle animation from the ONCC's TRAC and apply the rotations from the first frame of the animation 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 "folded" orientation or the "at attention" '''-noanim''' pose. A frame from 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 try==
===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:
#take two Oni characters (for simplicity, two characters who use the same skeleton: e.g., the Konokos from {{C|13}} and {{C|10}})
#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")
#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)
#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:
#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).
#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.
#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.
#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).
#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.
#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.
#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. ([[User:geyser|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. [[User:Geyser|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====
{|align=right
|http://geyser.oni2.net/edition/characters/gally/GLB_shot.png
|}
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 picture on the right);
*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 <strike>bitch</strike> 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 [http://geyser.oni2.net/edition/characters/gally/GLB_ripped.zip HERE] (well, not really as-is; I roundtripped it through 3D Exploration)
#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.
#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.
#There is a bunch of basic things that you want to do before actually adapting this character for Oni
##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 [http://geyser.oni2.net/edition/characters/gally/GLB_merged.zip THIS]. Reimport it into a new scene, and see what changed.
##Don't mind the "bone" objects for now. I just happened to include them in the rip, but I'm not sure why.
##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.
#Now you want to split the body mesh (part 18) into three parts and to add some placeholder meshes for the shoulders.
##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.
##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.
##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)
##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.
##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.
#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 [http://geyser.oni2.net/edition/characters/gally/GLB_almost.zip 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).
#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.
##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.
##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.
##Rotate Konoko's arms and shoulders to match Gally's pose. Try (0, +-65, 180) for shoulders and (0, +-65, 0) for arms.
##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", then all the upper body will move 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.
##*[http://geyser.oni2.net/edition/characters/gally/GLB_compact.zip HERE] is what you should get. Don't laugh too hard, and instead look at how well I matched the centers of Konoko's body parts with the tips of Gally's "bones". The only thing that's wrong at this point is that the shoulder parts are too far from their centers, and may end up sticking out of Gally's chest or back. To fix this, you can move, scale and rotate those parts in any way you like. Just remember to "Freeze all transforms" when you're done, especially if you've used scaling.
#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.
#When the reparenting and matching is over, you should get something like [http://geyser.oni2.net/edition/characters/gally/GLB_matched.zip THIS]. You can check that everything is OK simply by enabling the drawing of centers (either with the "eye" menu of a viewport, or with the "Center" filter), and then by alternatively middle-clicking "pelvis" and "pelvis2" (this selects the whole tree of either Gally, which we are unsure about, or the "compact Konoko", which we know to be OK because we only tweaked her [[TRTA]] a bit). If the centers and the local axes look the same for both Gally and Konoko, then Gally is OK too.
#And that's it, we're done. Now select all of Gally's meshes (as a tree, with Ctrl+T or middle-click), export to Collada ("selection only"), import into Oni (DAE to TRBS, TGA to TXMP, ONCC from '''konoko_generic''' and TRMA from '''ninjabot_tx''') and it should Just Work. And indeed it does. [http://geyser.oni2.net/edition/characters/gally/GLB_ready.zip HERE] is the input and [http://geyser.oni2.net/edition/characters/gally/level0_GUNNM.zip HERE] is the Oni-ready plugin (Windows only).
#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.
#This can be done in well under an hour - if you don't have to type a tutorial as you go, that is. Once you get the hang of this, you can save some time by completely skipping the "compact Konoko" part, and placing the new character's centers directly where you want them -- especially if the pose is as simple as this one, and/or if the model comes with a skeleton, or very clear anatomy, such as a robot. Challenges such as the [[AE:Iron Demon]] or the [[AE:BGI|BGI]] troopers/mecha come readily to mind, and could both use a tutorial.

[[Category:Modding tutorials]]

Blender

2022-11-20T23:46:49Z

Delano762: Blender-specific OniSplit information

Blender is a free and open-source program used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of modding with Blender==
[[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009, had the fewest problems in handling Oni's assets and animations, it was relatively easy to learn and use. Up until 2019, it was Oni community's 3D program of choice.

Blender at that time had a notoriously bad user interface and couldn't handle DAE files very well. [[#Oni-specific_issues_with_Blender|Besides other problems]], most importantly the expected rotation order and up-axis were different between XSI and Blender.

After an interface overhaul in version 2.80 Blender's user-friendliness and [http://oni.bungie.org/forum/viewtopic.php?pid=52588#p52588 support for vertex shading in DAE] was improved. At the same time more and more users had problems to run XSI on their PCs.

By 2019 demands got louder to support Blender made animations. [[OniSplit]] received an update (<tt>-blender</tt>) so it could read such animations. Also, rigging was never fully figured out in XSI so between 2020 and 2022 an [[Using the Rigify animation rig|animation rig]] tailor-fit for making Oni animations - alongside a new addon named [[BlenderOni]] - was created. It was the last nail in the coffin of XSI.

==Tutorials and resources==
With the abundance of tutorials for Blender on YouTube, creating our own introductory material would be reinventing the wheel. So instead we recommend watching some of the tutorials listed below and trying to make small personal projects in order to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (don't be misled by the silly name - this is one of the best Blender basics tutorials out there; it's also good if you know your basics already and you want to find out if you've missed anything)

Modelling:
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging:
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation:
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to what you might expect, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! (Curtis Holt)]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners (Jayanam)]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using the Rigify animation rig|HERE]]. The rig is based on the Rigify plugin for Blender and serves as the '''community's modern tool to create new character animations for Oni''', featuring both Forward and Inverse Kinematics – an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it – '''without it, the rig is extremely difficult to set up, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intended as an integral companion tool for the fan-made animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Blender-specific OniSplit information==
For detailed instructions on how to convert Oni assets to Blender-readable files, please check [[Importing_character_models#Blender-specific_OniSplit_information| Blender-specific OniSplit information.]]

==Oni-specific issues with Blender==
===Rotation order===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender. If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ"; this is because Blender reads the Euler angles [https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html from the bottom of the hierarchy] rather than the top. In other words, Oni reads XYZ starting with X, while Blender starts with Z.

You can demonstrate this by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below. The image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Differing up-axis===
To be expanded on later: Oni's "up" axis is Y, Blender's is Z.

===Units===
To be expanded on later: Oni's units are in the imperial system, not the metric one, though the 0.1-meter unit used by OniSplit is a good approximation of Oni's actual world unit of 4 inches.

===Lack of textures on animated models===
'''Currently there is no option in OniSplit for exporting animated models with textures in a way that Blender will import.''' While you don't need textures for animating, they are very useful, particularly in the case of Oni; the models are low-detail to a point where you can lose sense of which direction elbows and knees are facing if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually in the Shading tab.

{| class="wikitable"
|-
! Copying materials
|-
| [[Image:ABR_Copying_materials.png|200px|frameless|center]]
|-
|}

===Alpha transparency issue===
You will also most likely need to set the Shading settings on some of the body parts of a non-animated model in order to fix alpha transparency issues (much like in XSI); specifically, you'll need to connect the Alpha parameter of the Base Color node to any parameter in Principled BSDF that will work, such as Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how to do so at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]]
|-
|}

==Wanted==
Except for sounds, textures and text-oriented resources, Blender has the potential to be THE editor for Oni. Its powerful Python support is very useful for customization.

Additional imports/exports, XML/.oni file creation and configurations should be automated, and customization should be used to streamline workflows as much as possible. Tools in the form of addons should allow users to be artists instead of coders, speeding up development of the actual projects.

A successful modding community requires not one of these points, but all of them: documentation, tools and tutorials.

===Level editor===
* core geometry
* pathfinding
* "furniture" (OFGA) creation/placement
* editing of CJBO
* special gunk flag placement
* basic level shading (vertex shading)
* advanced level shading for OniX?

'''OFGA library'''

Objects that are used pretty often should be provided either by Blender Asset Browser or by a customized solution.
* Blender Asset Browser video demo: https://www.youtube.com/watch?v=gJC0y6HqyAU

===BSL editor===
Most events in Oni are fired using trigger volumes. There should be an editor to open the code of a trigger volume as soon as it's selected in Blender.

Also, character functions should editable when you select a character.

The editor should be context-sensitive to:
* level geometry: atmosphere, save points, win level, lose level
* objects: scripting of static and animated objects (cutscene editor)
* particle scripting
* character: after selecting a character there should be a button visible to edit the ONCC, TRBS, animations and textures (GIMP/Photoshop).

===Character editor===

'''Character library'''

There should be a way to place characters or character placeholders so that character collections (BINACHAR) can be saved to disk based on their positioning in the level model.

===Animation editor===
The core would be BlenderOni that is called as soon as a user chooses to create or edit an animation. It could be extended to edit TRAC.

===Particle editor===
A particle editor has been always missing in the community.

===Testing and publishing support===
There should be some linking to Vago and AEI for package creation and quick starting of levels for testing.

A secondary Oni installation could serve as a developer environment where only one level is present at a time. With OniX, it could be made possible to skip the menu UI and automatically load the current project.

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Importing character models

2022-11-20T23:43:06Z

Delano762: /* Blender-specific OniSplit information, formatting plus images */

This article covers the importing of new character models into Oni, but also how to export models from Oni. Generally speaking, you are going to want to use [[wikipedia:COLLADA|COLLADA]] as the "passthrough" format between your 3D program and Oni, as this is exactly what COLLADA was designed for. In this article, COLLADA is referred to as "Collada" (because who enjoys being shouted at?), or by ".dae file" (because that is the file suffix for COLLADA).

==Modding tools==
===OniSplit===
This is the program that we use to get models into and out of Oni. It is a command line tool. There are GUI wrappers for OniSplit that cover most of its functions (see [[Vago (tool)]], but modders sometimes have to call it from the command line (or use the direct command line input feature in a GUI) to take full advantage of OniSplit's abilities.

===3D programs===
====Blender====
[[Blender]] is the community's current 3D software of choice, allowing for 3D modeling, animating, and more.

Blender rocks when it comes to [[Lightmapping levels|lightmapping levels]]. 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]]).

====XSI====
Softimage XSI is a Windows-only 3D software that went discontinued in 2014, and [https://www.moddb.com/downloads/autodesk-softimage-mod-tool-75 a free version of it from 2008] used to to be the community's modding tool of choice before moving on to Blender. A number of Oni-related addons, tools and tutorials were developed for it can be still found and used. It has detailed documentation and is versatile, whether working with characters or levels, though highly obsolete.

===File converters===
====Autodesk FBX====
Check out {{AutodeskFBX}} (primarily the FBX converter) if your tool can reliably import/export FBX but has trouble with Collada.

==Basic importing and exporting==
===Exporting from Oni to Collada===
OniSplit allows you to export .dae files from both [[TRBS]] and [[ONCC]]. Though all the 3D data is in the TRBS, the textures are listed in the [[TRMA]] file, which is only visible from the ONCC, not the TRBS. Thus, if you want to use the textures while editing the model, convert the ONCC, not the TRBS, into Collada. The instructions below assume that you want the textured model, and thus illustrate how to export the ONCC.

First, you need to find the class name for the character you want to export. You can accomplish this by going into Oni, loading the level in which the desired character appears, and then enabling the shapeshifter cheat -- but you have to do this by turning on [[Developer Mode]], not by entering the "shapeshifter" cheat code, because the regular cheat code does not display the console output that you need. Once Dev Mode is on, press F8 until you reach the desired character. You should see the message "character class ''number'' '''''string'''''". The number is unimportant, but write down the string, because that is the class name which provides the basis for the names of the ONCC and TRBS.

In this example, we'll export one of Konoko's models. For Konoko, we don't even need to open Oni to find the name of an ONCC because we have [[Konoko#In-game_outfits|this handy table]]. Let's use Konoko in her police uniform; you can see from the table that this is ONCCk3 and that it's found in level2_Final.

Next, you need to decide on the pose in which your character will be exported. See the "Poses" section below for guidance. Without making this example more complicated, we only have two choices for pose: default (folded) and -noanim (standing at attention); we are going to use the second option, for a more visually pleasing result. Here are the steps for getting your desired character in .dae format. Substitute backward slashes for forward ones if you are in Windows.

:1. Create a couple of folders in a convenient place. One folder will receive a whole bunch of files, and the second folder will hold the exported model. We'll call these paths "splitOutput/" and "modelOutput/" respectively.
:2. On the command line, go to the directory "Oni/GameDataFolder/", where "Oni/" means the path to your game.
:3. Split the desired level's data into its component resources with OniSplit. Where you see just "onisplit" in the following commands, you should take that to mean "C:\path\to\OniSplit.exe" in Windows or "mono /path/to/OniSplit.exe" on Macs (Mono is a third-party package that you need to run .NET applications in macOS):
::<tt>onisplit -export splitOutput/ level2_Final.dat</tt>
:4. Convert the desired character's model data into Collada:
::<tt>onisplit -extract:dae modelOutput/ -noanim splitOutput/ONCCk3.oni</tt>

This will create the file '''ONCCk3.dae''', and its supporting textures in TGA format, in modelOutput/. Note that only the highest level of detail (LOD) model will be exported using this method. See [[XML:TRBS]] for a method which exports all 5 LOD models.

Note that if you want to extract the model with a pose besides folded or -noanim, you need to have the animation data (the [[TRAC]] and [[TRAM]] .oni files) in the same folder as the model data (the ONCC and its related files). In vanilla (un-modded) Oni, animations for many characters (including Konoko) are only in level0_Final, and, as you saw above, model data is found in whichever level that character appears in. Extracting a model in the pose of your choice will be simpler if you have the [[AE]] installed, as it globalizes character data, placing it all in the level0_Final files in the AE's GameDataFolder. With vanilla Oni, you will have to split both level0_Final and level''x''_Final and then combine their files into one folder before you can perform the "-extract:dae" operation using the "-anim" tag that is discussed below.

===Importing from Collada into Oni===
When importing characters, the simplest method is to generate a whole body set ([[TRBS]]) from one .dae file. To convert your 3D model, let's say that you saved it in Collada format with the name "TRBSnewchar.dae". Run the command:
:<tt>onisplit -create:trbs DAEtoONI/ TRBSnewchar.dae</tt>

This will create '''TRBSnewchar.oni''' in the folder DAEtoONI. Because it was created from a single .dae file, this TRBS will contain 5 identical models for the 5 levels of detail (LOD) that Oni supports for each character. You have to import by XML in order to specify a different .dae for every LOD; see [[XML:TRBS]] for more info.

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 if you were editing a model exported from Oni). Possibly a future version of OniSplit can automatically generate a TRMA and TXMPs if the .dae file has textures.

Note that your file should be named appropriately if you want it to be looked up by name from one or more of Oni's existing ONCCs, or a new one of your own creation.

To actually test the model in-game, you should [[Making a mod package|create a mod package]] for it, place the package in Oni/AE/packages/, and select it in the AE Installer. The older method of testing your work is to rebuild the level by running "onisplit -import" on a folder containing your TRBS and all the other .oni files for a level, but this only creates a set of level files that you can use on your computer, and is inherently a disorganized approach to keeping track of your work. Creating an AE package will allow you to share your work with other players.

Please note that a final character mod package should contain multiple LOD models for your character. Filling all 5 slots with distinct models is not necessary; many modders create only two or three LOD models and fill the lower LOD slots with the simpler model(s) and the highest slot with the full-detail model, e.g.:
:# TRBSnewchar_low.dae
:# TRBSnewchar_low.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_high.dae

An ONCC contains much more information than just links to TRBS and TRMA, and thus can not be generated automatically. See [[XML:ONCC]] on how to create such a file, and then import the character with this class data into Oni. The easiest way to try out an imported character in Oni is to name your imported TRBS so that it replaces an existing one and no ONCC editing is needed. The next step up is to clone an existing ONCC (in XML) and modify it to link to your new TRBS file(s).

==Blender-specific OniSplit information==
This section contains OniSplit commands specific to Blender, and related settings in Blender necessary for assets to work.

===Blender settings for importing and exporting COLLADA files===
====Importing====
In the Collada Import Data Options, make sure to check Import Units. Failure to do so will result in scaling issues, which are not easy to fix.

Before importing TRAM files, set the scene frame rate to 60fps.

{| class="wikitable"
|-
! Collada import settings !! Scene settings
|-
| [[Image:BlenderImportSettings.png|200px|frameless|center]] || [[Image:BlenderSceneSettings.png|300px|frameless|center]]
|-
|}
====Exporting====
When exporting TRBS, be sure to delete the default light and camera from the scene, or you can select all 19 body parts, then in the Export Main Tab, select Selection Only

When exporting TRAM, select all 19 body parts, then in the Collada export options, under the Main Tab: select Selection Only, Geom Tab: select Triangulate, Anim Tab: select Curves.

{| class="wikitable"
|-
! Blender Collada export settings
|-
| [[Image:BlenderColladaExportSettings.png|500px|frameless|center]]
|-
|}

===Blender-specific OniSplit commands===
*Convert TRBS.oni to Blender compatible dae:
-extract:'''dae''' To_blender -noanim -blender Original\TRBSkonoko_body_high.oni

*Convert ONCC.oni to Blender compatible dae with textures:

-extract:'''dae''' To_blender -noanim -blender Original\ONCCkonoko_generic.oni

Be sure to include the TMXP.oni files with the ONCC.oni file.

*Convert TRAM.oni to Blender compatible dae - '''textureless''', as exporting animations with textured models does not work yet:

-extract:'''xml''' To_blender -anim-body:Original\TRBSkonoko_body_high.oni -blender Original\TRAMKONCOMkick_heavy.oni

This will create a TRAM.dae along with an .xml file, which is needed for importing back to Oni. You will be also able to tell that everything went okay when you see
<tt>AnimationDaeWriter: custom axis conversion</tt>
on output. If you don’t, you’re most likely doing something wrong.

*Convert TRBS.dae from Blender to .oni:
-create:'''trbs''' From_blender -blender From_blender\TRBSkonoko_body_high.dae

*Convert TRAM.dae from Blender to .oni
-create From_blender -blender From_blender\TRAMKONCOMkick_heavy.xml
The TRAMKONCOMkick_heavy.xml links to the TRAMKONCOMkick_heavy.dae from Blender which needs to be in the same location as the .xml file.

===Troubleshooting===

Known Issues between Blender 2.83 and OniSplit 0.9.99.2

1) Importing a .dae file results in the following error message:
"Schema validation (Error): Error: ERROR_REQUIRED_ATTRIBUTE_MISSING Element: technique, Attribute: sid"

Solution: Open the .dae file in a text editor, find all instances of <tt><technique></tt> and replace with <tt><technique sid="common"></tt>

==Poses==
===Oni's default orientation===
This pose, where the body parts are all at zero rotation, is usually referred to in the community as the "folded pose". 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, in the default pose, you can see the "true" translations (offsets) 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===
[[Image:Konoko_bodyparts.png|thumbnail|right|283px]]
Supplying the '''-noanim''' switch to OniSplit yields the "standing at attention" pose, a much less visually awkward pose than the default "folded pose". Note that "-noanim" goes in between the destination directory and the source file name:
:'''onisplit -extract:dae modelOutput/ -noanim ONCCkonoko_generic.oni'''

The result will look something the picture on the right, but the model will have her legs together and her arms by her side.

To produce this pose, these rotations are used:
:(0,90,90) for the pelvis
:(0,180,0) for both thighs
:(90,90,90) for the left shoulder
:(-90,-90,90) for the right shoulder
:(0,90,0) for the left biceps
:(0,-90,0) for the right biceps
:(-90,0,0) for the left hand/fist
:(90,0,0) for the right hand/fist
:(0,0,0) for all other parts
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.

===Idle pose===
If you use '''-extract:dae TargetFolder ONCCkonoko_generic.oni''', taking care that you have the TRAC/TRAM files next to the ONCC, OniSplit will look up the idle animation from the ONCC's TRAC and apply the rotations from the first frame of the animation 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 "folded" orientation or the "at attention" '''-noanim''' pose. A frame from 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 try==
===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:
#take two Oni characters (for simplicity, two characters who use the same skeleton: e.g., the Konokos from {{C|13}} and {{C|10}})
#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")
#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)
#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:
#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).
#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.
#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.
#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).
#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.
#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.
#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. ([[User:geyser|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. [[User:Geyser|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====
{|align=right
|http://geyser.oni2.net/edition/characters/gally/GLB_shot.png
|}
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 picture on the right);
*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 <strike>bitch</strike> 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 [http://geyser.oni2.net/edition/characters/gally/GLB_ripped.zip HERE] (well, not really as-is; I roundtripped it through 3D Exploration)
#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.
#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.
#There is a bunch of basic things that you want to do before actually adapting this character for Oni
##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 [http://geyser.oni2.net/edition/characters/gally/GLB_merged.zip THIS]. Reimport it into a new scene, and see what changed.
##Don't mind the "bone" objects for now. I just happened to include them in the rip, but I'm not sure why.
##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.
#Now you want to split the body mesh (part 18) into three parts and to add some placeholder meshes for the shoulders.
##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.
##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.
##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)
##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.
##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.
#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 [http://geyser.oni2.net/edition/characters/gally/GLB_almost.zip 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).
#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.
##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.
##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.
##Rotate Konoko's arms and shoulders to match Gally's pose. Try (0, +-65, 180) for shoulders and (0, +-65, 0) for arms.
##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", then all the upper body will move 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.
##*[http://geyser.oni2.net/edition/characters/gally/GLB_compact.zip HERE] is what you should get. Don't laugh too hard, and instead look at how well I matched the centers of Konoko's body parts with the tips of Gally's "bones". The only thing that's wrong at this point is that the shoulder parts are too far from their centers, and may end up sticking out of Gally's chest or back. To fix this, you can move, scale and rotate those parts in any way you like. Just remember to "Freeze all transforms" when you're done, especially if you've used scaling.
#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.
#When the reparenting and matching is over, you should get something like [http://geyser.oni2.net/edition/characters/gally/GLB_matched.zip THIS]. You can check that everything is OK simply by enabling the drawing of centers (either with the "eye" menu of a viewport, or with the "Center" filter), and then by alternatively middle-clicking "pelvis" and "pelvis2" (this selects the whole tree of either Gally, which we are unsure about, or the "compact Konoko", which we know to be OK because we only tweaked her [[TRTA]] a bit). If the centers and the local axes look the same for both Gally and Konoko, then Gally is OK too.
#And that's it, we're done. Now select all of Gally's meshes (as a tree, with Ctrl+T or middle-click), export to Collada ("selection only"), import into Oni (DAE to TRBS, TGA to TXMP, ONCC from '''konoko_generic''' and TRMA from '''ninjabot_tx''') and it should Just Work. And indeed it does. [http://geyser.oni2.net/edition/characters/gally/GLB_ready.zip HERE] is the input and [http://geyser.oni2.net/edition/characters/gally/level0_GUNNM.zip HERE] is the Oni-ready plugin (Windows only).
#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.
#This can be done in well under an hour - if you don't have to type a tutorial as you go, that is. Once you get the hang of this, you can save some time by completely skipping the "compact Konoko" part, and placing the new character's centers directly where you want them -- especially if the pose is as simple as this one, and/or if the model comes with a skeleton, or very clear anatomy, such as a robot. Challenges such as the [[AE:Iron Demon]] or the [[AE:BGI|BGI]] troopers/mecha come readily to mind, and could both use a tutorial.

[[Category:Modding tutorials]]

File:Blender Collada export settings.png

2022-11-20T23:37:02Z

Delano762: Blender Collada export settings, showing mainly how Curves should be enabled instead of samples.

== Summary ==
Blender Collada export settings, showing mainly how Curves should be enabled instead of samples.

File:Blender scene settings.png

2022-11-20T23:35:27Z

Delano762: Blender scene settings showing that the frame rate should always be set to 60 FPS.

== Summary ==
Blender scene settings showing that the frame rate should always be set to 60 FPS.

File:Blender import settings.png

2022-11-20T23:34:30Z

Delano762: Blender import settings showing that Import Units should be always checked.

== Summary ==
Blender import settings showing that Import Units should be always checked.

OniSplit

2022-11-20T22:57:15Z

Delano762: /* Blender support */

{{TOCfloat|side=right}}
{{Hatnote|Before reading this page, it's a good idea to be familiar with basic Oni [[game data terminology]].}}
'''OniSplit''', written by [[User_talk:Neo|Neo]], is an integral part of the [[Anniversary Edition]] and an essential modding tool on its own. It is a command line tool which can import and export almost all kinds of Oni game data, including textures, sound, 3D models, level geometry and combat animations. Its name comes from its original purpose, which was breaking Oni's level data files into individual resources. Later, the ability to convert those resources' data between Oni's format and standard file formats was added. OniSplit incorporates the latest [[OBD|knowledge about Oni's game data]], and it is currently the community's main modding tool.

:''Subpages:'' [[/Change_log|Change log]] (past versions), [[/WIP|WIP notes]] (upcoming versions)

==Getting it==
===Download links===
* Latest release of OniSplit: [http://mods.oni2.net/node/38 v0.9.99.2] ([http://websvn.illy.bz/dl.php?repname=Oni2&path=%2FOniSplit%2F&isdir=1 source code])
* The current GUI for OniSplit is [[Vago (tool)|Vago]]. '''You should try the GUI to see if it does what you need before working with OniSplit on the command line.'''

===Requirements===
*Windows: [https://dotnet.microsoft.com/en-us/download/dotnet-framework .NET framework]
*macOS: [https://www.mono-project.com/download/stable/ Mono framework]

==Workflow==
OniSplit is used in up to four different stages when modding:
{|
|rowspan="2"|'''OUT'''
|''Exporting'' - using the <tt>-export</tt> command, a [[Dat|level data file]] is broken into its component resources, .oni files.
|-
|style="border-style: solid; border-width: 0 0 1px 0"|''Extracting'' - using the <tt>-extract</tt> commands, .oni files are converted to standard-format files that can be edited in various third-party programs.
|-
|rowspan="2"|<center>'''IN'''</center>
|''Creating'' - using the <tt>-create</tt> commands, standard-format files are converted into .oni files.
|-
|''Importing'' - using the <tt>-import</tt> command, a folder of .oni files is combined into a level data file.
|}

Note that "extracting" refers to a conversion from one format to another, but "exporting" only refers to the creation of .oni files from a .dat file. When exporting, no conversion or re-formatting is taking place; the data is simply being copied out of a .dat (any connected binary data in .raw/.sep files will be concatenated to the data from the .dat when making the .oni).

==Beginner's tips==
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
In Windows, there are several options through which you can use OniSplit - out of which it is recommended to get Vago and CMDer:
* [[Vago (tool)|Vago]] is a GUI for OniSplit which allows you to handle all general conversions, save your sessions as project files, input manual commands if needed, and more. The two downsides of it is that it doesn't support Blender yet, forcing the users input commands manually, which in turn are not stored upon ending the session.
* [https://cmder.app/ CMDer] is an excellent alternative to cmd.exe. It can be customized to allow starting it from any folder you pick with the context menu, and it also stores the most recently used commands after ending the session. Currently it is highly useful for Blender-related operations.
* Command Prompt/cmd.exe. Windows' default command line interpreter, it's a poor choice as it does not store most recently used commands.

On Macs, the command line is found in the Terminal app (/Applications/Utilities) (press Command-Spacebar and type "Terminal" to get there faster).

===OniSplit syntax===
The basic syntax is:
{|
|-
|'''Windows'''||<tt>OniSplit.exe -create:trbs C:\Games\Oni\SomeFolder -normals C:\Games\Oni\Modding\TRBSMyNewChar.dae</tt>
|-
|'''Mac'''||<tt>mono OniSplit.exe -create:trbs /Games/Oni/SomeFolder -normals /Games/Oni/Modding/TRBSMyNewChar.dae</tt>
|}

Here's how it breaks down:
{|
! style="width:130px"|
|- valign="top"
|'''Invocation'''
|Windows can refer to the program directly, but Macs use Mono to run the .NET app; note also that if OniSplit.exe is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.
|-
|'''Option'''||The command.
|- valign="top"
|'''Path to folder'''||Whether destination or source, the path which is a folder comes first. Use the full path to the folder (starting from "C:\", or "/" on Macs).
|-
|'''Option flags'''||The flags that can optionally go with this command, separated by spaces.
|- valign="top"
|'''Path to file'''||Whether destination or source, the path of the file comes second. Use the full path to the file (starting from "C:\", or "/" on Macs). One exception to this parameter being a file is when using <tt>-create</tt> to make a level, in which case this is where you supply the source folder.
|}

===CLI tips===
*Command line interfaces (CLI) usually supply an auto-complete feature to save on typing. If you've typed enough of a file/folder name to identify it, press the Tab key and the rest should fill in. In Windows, you may not get the right path name autocompleted on the first try if there are multiple possible autocompletions based on the names in that directory, so keep pressing Tab to cycle through all possibilities. On Macs, if you have not typed enough of the name to narrow it down to a single autocompletion, you will hear an error sound. Double-tap Tab to see a list of possible autocompletions, then keep typing until you have narrowed it down to one of those and then hit Tab to fill in the rest of its name.

*Note that you can also drag files/folders into the window and the path will magically appear; in cases where you don't need to use a wildcard, this is the fastest way to build an OniSplit command.

===Wildcards===
Wildcards can be used to supply patterns to CLI programs. The wildcard is simply the <tt>*</tt> character. For instance:
OniSplit.exe -export:TRAM* <destination> <source .dat>
will export all the TRAMs in the source .dat into the destination folder. Using "TRAMKON*" would export all of Konoko's animations.

===Spaces in paths===
Command line interfaces (CLI) do not recognize spaces as a possible part of a path name because spaces are what separate the terms in your commands. The best course of action is to not use paths with spaces in their names! But if you must, you can use quotes to tell the CLI that a certain string is a single path:

'''C:\Games\Oni\>'''OniSplit.exe -list "My Mod Folder\level5_Final.dat"

This works in the Mac Terminal too, but you can also use the escape character, <tt>\</tt>. Also, other characters like <tt>(</tt> need to be escaped as well if you do not use quotes:

'''MyMac%''' mono OniSplit.exe -list My\ Mods\ \(In\ Progress\)/level5_Final.dat

But as mentioned, the best practice is to not use any characters besides the alphabet and numbers. It makes your life simpler, and if you ask for help on the forum with a command, no one wants to have to read your long path with lots of spaces or escaped characters in it ;-)

===Reading the commands below===
*The following commands should be complete, but the current list can be obtained by calling OniSplit with the <tt>-help</tt> option. You should also use <tt>-version</tt> to make sure you're using the latest version, the number of which is given in the "Download links" section above.

*Sample usages are given after certain commands. These are in DOS style, so if you are on a Mac, simply flip the <tt>\</tt>s to <tt>/</tt>s and make "C:\" into a leading "/".

*Optional flags are listed in square brackets simply to indicate that they're optional; don't enter the brackets when typing a command.

Note that only the .dat file from a level's data files is mentioned. The .raw and .sep files will be accessed by OniSplit as necessary when working with the .dat file that you gave the name of.
{{Divhide|end}}

==Commands==
===Conversion between .dat and .oni===
{|
! style="width:430px"|
|-
|<code>-list <file name></code>||Lists the named resources contained in a .dat (see [[OBD:File_types/Named|HERE]] for info on unnamed resources)
|-
|<code>-export <destination directory> <dat file></code>||Breaks .dat file into .oni files
|-
|<code>-export:<pattern> <destination directory> <dat file></code>||Exports named resource (wildcards also allowed) from .dat file
|- valign="top"
|<code>-import <source directory> <new dat file></code>||Compiles level files from source directory using the name you supply for the .dat file; tries to get target file format from source SNDD, but it's better to use the :sep or :nosep variants below
|-
|colspan="2"|To create level5_Final.dat/.raw[/.sep] from the files in MyNewLevel\: <code>OniSplit.exe -import C:\Oni\MyNewLevel\ C:\Oni\GameDataFolder\level5_Final.dat</code>
|-
|<code>-import:sep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw/.sep format (Mac and PC Demo)
|-
|<code>-import:nosep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw format (PC retail)
|}
:Note that <tt>-import</tt> will search subdirectories too. If you find having hundreds or thousand of files .oni in one directory to be unmanageable you can always group them in subdirectories any way you like. The only exception is that a subdirectory named "noimport" or "_noimport" is always ignored.

===Management of .oni files===
Sometimes you want to move some .oni files out of a larger folder of .onis. You could do this manually, but OniSpit knows which files depend on others. It will also look for those dependencies in subfolders beneath the level of the file you supply the name of. The filename field supports wildcards. This is mostly used by the [[AE]] Installer rather than modders themselves.
{|
|<code>-deps <oni file></code>||Displays a list of .oni files that the specified .oni file depends on
|-
|<code>-copy <destination directory> <oni file></code>||Copies .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move <destination directory> <oni file></code>||Moves an .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move:overwrite <destination directory> <oni file></code>||Moves an .oni file and its dependencies; overwrites any existing .oni files
|-
|<code>-move:delete <destination directory> <oni file></code>||Moves an .oni file and its dependencies; doesn't overwrite; deletes source files
|}

===Conversion between .oni/.dat and 3rd party formats===
====Textures====
Unless mentioned otherwise, source filenames support wildcards. See [[Modifying textures|HERE]] for a detailed tutorial. The <tt>-extract</tt> commands can work with .oni files (a single file or several files if you use the wildcard), or rip all the TXMPs from a .dat file.
{|
|<code>-extract:dds <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into DDS files
|-
|<code>-extract:tga <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into TGA files
|-
|<code>-extract:png <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into PNG files
|-
|<code>-create:txmp <destination directory> [-genmipmaps] [-nouwrap] [-novwrap] <nowiki>[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]</nowiki> [-envmap:texture_name] <image file></code>
|valign=top|Creates .oni file from image file (PNG, TGA, or DDS)
|}

====Models====
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can be exported to the Wavefront .obj and COLLADA .dae formats. For details see [[Importing character models]] and [[Importing weapon models]]. The generic <tt>-extract</tt> commands can work with .oni files (a single file, or several files if you use the wildcard), or rip all the TXMP from a .dat file. TRBS and ONCC support additional <tt>-noanim</tt> and <tt>-anim</tt> options for <tt>-extract:dae</tt>; see [[Importing character models]] for details. Imported geometry must only contain triangles.
{|
! style="width:540px"|
|- valign="top"
|<code>-extract:obj <destination directory> <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Wavefront OBJ files
|- valign="top"
|<code>-extract:dae <destination directory> [-noanim] <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Collada DAE files
|-
|<code>-create:m3gm <destination directory> [-tex:texture_name] <OBJ file></code>||Creates a M3GM .oni from an .obj file
|-
|<code>-create:trbs <destination directory> [-cel] [-normals] <DAE file></code>||Creates a TRBS .oni from a .dae file
|}

Note on -noanim parameter: Normally OniSplit exports the character with an idle animation. If you use -noanim the character is exported in "I" pose, also the pelvis has the coordinates x=0, y=0, z=0.

====Levels====
OniSplit can convert AKEV files (level geometry) and the associated file types to and from DAE format:
{|
|<code>-extract:dae <destination directory> <AKEV.oni file></code>||Extracts 3D data in AKEV and related resources from dependencies into Collada file
|}

The next two steps are used on a folder in which you have placed the DAE and XML-formatted instances of the required files, as well as textures in TGA format. See [http://oni.bungie.org/forum/viewtopic.php?id=1515 HERE] for details.
{|
|- valign="top"
|<code>-create <destination directory> [-genmipmaps] [-format:dxt1] <source directory></code>||Converts all AKEV and related instances to .oni files
|- valign="top"
|<code>-import:nosep <source directory> <target file name>.dat</code>||The standard command for creating .dat/.raw files from .oni files (remember to use the import:sep option on Mac!)
|}

====Sounds====
The sounds in Windows Oni are stored in WAV format, and on Macs are stored in AIFF format. This also means creating each of your SNDD files in both formats in order to work on both platforms.
{|
|<code>-extract:wav <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .wav files
|-
|<code>-extract:aif <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .aif files
|}

====Text====
{|
|<code>-extract:txt <destination directory> <dat/oni file></code>||Rips text data from a SUBT .oni file (or all SUBTs from a .dat) as .txt files
|-
|<code>-create:subt <destination directory> <TXT file></code>||Creates a SUBT .oni file from a .txt file
|}

====XML====
One of the latest features is conversion of .oni files to and from an XML file, or an XML metafile and related 3rd-party format files. XML files are easier to read and edit.
::Currently XML export/import is limited to files that do not have raw/sep parts. 2-way conversion is known to work for [[BINA]], [[CONS]], [[DOOR]], [[DPge]], [[FILM]], [[HPge]], [[IGHH]], [[IPge]], [[M3GM]], [[OBAN]], [[ONCC]], [[ONCV]], [[ONLD]], [[ONLV]], [[ONGS]], [[ONSK]], [[ONVL]], [[ONWC]], [[OPge]], [[OSBD]], [[PSpc]], [[PSpL]], [[PSUI]], [[TRAC]], [[TRAM]], [[TRIG]], [[TRGE]], [[TRMA]], [[TRSC]], [[TXMB]], [[TXMP]], [[WMCL]], [[WMDD]], [[WMM_]], [[WPge]].
:::For detailed examples and tutorials, see [[XML|HERE]]
{|
|<code>-extract:xml <destination directory> <oni file></code>||Extracts .oni file and all related resources to XML files and 3rd-party formats
|-
|<code>-create <destination directory> <XML file></code>||Creates an .oni file from an XML file
|}

====Blender support====
[[Blender]] by default has a number of issues with most of Oni's assets, however, OniSplit allows exporting them to Blender-readable files with the <tt>-blender</tt> flag.

For more detailed information on how to use the <tt>-blender</tt> flag, please check [[Importing_character_models#Blender-specific_OniSplit_information|Blender specific OniSplit information]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]][[Category:Modding tutorials]]

Importing character models

2022-11-20T22:39:21Z

Delano762: Added Blender-specific OniSplit information

This article covers the importing of new character models into Oni, but also how to export models from Oni. Generally speaking, you are going to want to use [[wikipedia:COLLADA|COLLADA]] as the "passthrough" format between your 3D program and Oni, as this is exactly what COLLADA was designed for. In this article, COLLADA is referred to as "Collada" (because who enjoys being shouted at?), or by ".dae file" (because that is the file suffix for COLLADA).

==Modding tools==
===OniSplit===
This is the program that we use to get models into and out of Oni. It is a command line tool. There are GUI wrappers for OniSplit that cover most of its functions (see [[Vago (tool)]], but modders sometimes have to call it from the command line (or use the direct command line input feature in a GUI) to take full advantage of OniSplit's abilities.

===3D programs===
====Blender====
[[Blender]] is the community's current 3D software of choice, allowing for 3D modeling, animating, and more.

Blender rocks when it comes to [[Lightmapping levels|lightmapping levels]]. 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]]).

====XSI====
Softimage XSI is a Windows-only 3D software that went discontinued in 2014, and [https://www.moddb.com/downloads/autodesk-softimage-mod-tool-75 a free version of it from 2008] used to to be the community's modding tool of choice before moving on to Blender. A number of Oni-related addons, tools and tutorials were developed for it can be still found and used. It has detailed documentation and is versatile, whether working with characters or levels, though highly obsolete.

===File converters===
====Autodesk FBX====
Check out {{AutodeskFBX}} (primarily the FBX converter) if your tool can reliably import/export FBX but has trouble with Collada.

==Basic importing and exporting==
===Exporting from Oni to Collada===
OniSplit allows you to export .dae files from both [[TRBS]] and [[ONCC]]. Though all the 3D data is in the TRBS, the textures are listed in the [[TRMA]] file, which is only visible from the ONCC, not the TRBS. Thus, if you want to use the textures while editing the model, convert the ONCC, not the TRBS, into Collada. The instructions below assume that you want the textured model, and thus illustrate how to export the ONCC.

First, you need to find the class name for the character you want to export. You can accomplish this by going into Oni, loading the level in which the desired character appears, and then enabling the shapeshifter cheat -- but you have to do this by turning on [[Developer Mode]], not by entering the "shapeshifter" cheat code, because the regular cheat code does not display the console output that you need. Once Dev Mode is on, press F8 until you reach the desired character. You should see the message "character class ''number'' '''''string'''''". The number is unimportant, but write down the string, because that is the class name which provides the basis for the names of the ONCC and TRBS.

In this example, we'll export one of Konoko's models. For Konoko, we don't even need to open Oni to find the name of an ONCC because we have [[Konoko#In-game_outfits|this handy table]]. Let's use Konoko in her police uniform; you can see from the table that this is ONCCk3 and that it's found in level2_Final.

Next, you need to decide on the pose in which your character will be exported. See the "Poses" section below for guidance. Without making this example more complicated, we only have two choices for pose: default (folded) and -noanim (standing at attention); we are going to use the second option, for a more visually pleasing result. Here are the steps for getting your desired character in .dae format. Substitute backward slashes for forward ones if you are in Windows.

:1. Create a couple of folders in a convenient place. One folder will receive a whole bunch of files, and the second folder will hold the exported model. We'll call these paths "splitOutput/" and "modelOutput/" respectively.
:2. On the command line, go to the directory "Oni/GameDataFolder/", where "Oni/" means the path to your game.
:3. Split the desired level's data into its component resources with OniSplit. Where you see just "onisplit" in the following commands, you should take that to mean "C:\path\to\OniSplit.exe" in Windows or "mono /path/to/OniSplit.exe" on Macs (Mono is a third-party package that you need to run .NET applications in macOS):
::<tt>onisplit -export splitOutput/ level2_Final.dat</tt>
:4. Convert the desired character's model data into Collada:
::<tt>onisplit -extract:dae modelOutput/ -noanim splitOutput/ONCCk3.oni</tt>

This will create the file '''ONCCk3.dae''', and its supporting textures in TGA format, in modelOutput/. Note that only the highest level of detail (LOD) model will be exported using this method. See [[XML:TRBS]] for a method which exports all 5 LOD models.

Note that if you want to extract the model with a pose besides folded or -noanim, you need to have the animation data (the [[TRAC]] and [[TRAM]] .oni files) in the same folder as the model data (the ONCC and its related files). In vanilla (un-modded) Oni, animations for many characters (including Konoko) are only in level0_Final, and, as you saw above, model data is found in whichever level that character appears in. Extracting a model in the pose of your choice will be simpler if you have the [[AE]] installed, as it globalizes character data, placing it all in the level0_Final files in the AE's GameDataFolder. With vanilla Oni, you will have to split both level0_Final and level''x''_Final and then combine their files into one folder before you can perform the "-extract:dae" operation using the "-anim" tag that is discussed below.

===Importing from Collada into Oni===
When importing characters, the simplest method is to generate a whole body set ([[TRBS]]) from one .dae file. To convert your 3D model, let's say that you saved it in Collada format with the name "TRBSnewchar.dae". Run the command:
:<tt>onisplit -create:trbs DAEtoONI/ TRBSnewchar.dae</tt>

This will create '''TRBSnewchar.oni''' in the folder DAEtoONI. Because it was created from a single .dae file, this TRBS will contain 5 identical models for the 5 levels of detail (LOD) that Oni supports for each character. You have to import by XML in order to specify a different .dae for every LOD; see [[XML:TRBS]] for more info.

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 if you were editing a model exported from Oni). Possibly a future version of OniSplit can automatically generate a TRMA and TXMPs if the .dae file has textures.

Note that your file should be named appropriately if you want it to be looked up by name from one or more of Oni's existing ONCCs, or a new one of your own creation.

To actually test the model in-game, you should [[Making a mod package|create a mod package]] for it, place the package in Oni/AE/packages/, and select it in the AE Installer. The older method of testing your work is to rebuild the level by running "onisplit -import" on a folder containing your TRBS and all the other .oni files for a level, but this only creates a set of level files that you can use on your computer, and is inherently a disorganized approach to keeping track of your work. Creating an AE package will allow you to share your work with other players.

Please note that a final character mod package should contain multiple LOD models for your character. Filling all 5 slots with distinct models is not necessary; many modders create only two or three LOD models and fill the lower LOD slots with the simpler model(s) and the highest slot with the full-detail model, e.g.:
:# TRBSnewchar_low.dae
:# TRBSnewchar_low.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_high.dae

An ONCC contains much more information than just links to TRBS and TRMA, and thus can not be generated automatically. See [[XML:ONCC]] on how to create such a file, and then import the character with this class data into Oni. The easiest way to try out an imported character in Oni is to name your imported TRBS so that it replaces an existing one and no ONCC editing is needed. The next step up is to clone an existing ONCC (in XML) and modify it to link to your new TRBS file(s).

==Blender-specific OniSplit information==
This section contains OniSplit commands specific to Blender, and related settings in Blender necessary for assets to work.

===Blender settings for importing and exporting COLLADA files===
====Importing====
In the Collada Import Data Options, make sure to check Import Units. Failure to do so will result in scaling issues, which are not easy to fix.

Before importing TRAM files, set the scene frame rate to 60fps.
====Exporting====
When exporting TRBS, be sure to delete the default light and camera from the scene, or you can select all 19 body parts, then in the Export Main Tab, select Selection Only

When exporting TRAM, select all 19 body parts, then in the Collada export options, under the Main Tab: select Selection Only, Geom Tab: select Triangulate, Anim Tab: select Curves.
===Troubleshooting===

Known Issues between Blender 2.83 and OniSplit 0.9.99.2

1) When importing .dae file you get the error message "Schema validation (Error): Error: ERROR_REQUIRED_ATTRIBUTE_MISSING Element: technique, Attribute: sid"

Solution: Open the .dae file in a text editor, find all instances of <technique> and replace with <technique sid="common">

===Blender-specific OniSplit commands===
Convert TRBS.oni to Blender compatible dae:
-extract:dae To_blender -noanim -blender Original\TRBSkonoko_body_high.oni

Convert ONCC.oni to Blender compatible dae with textures:

-extract:dae To_blender -noanim -blender Original\ONCCkonoko_generic.oni

Be sure to include the TMXP.oni files with the ONCC.oni file

Convert TRAM.oni to Blender compatible dae - textureless, as exporting animations with textured models does not work yet:

-extract:xml To_blender -anim-body:Original\TRBSkonoko_body_high.oni -blender Original\TRAMKONCOMkick_heavy.oni

This will create a TRAM.dae along with an .xml file, which is needed for importing back to Oni.
You will be also able to tell that everything went okay when you see
AnimationDaeWriter: custom axis conversion.
on output. If you don’t, you’re most likely doing something wrong.

Convert TRBS.dae from Blender to .oni:
-create:trbs From_blender -blender From_blender\TRBSkonoko_body_high.dae

Convert TRAM.dae from Blender to .oni
-create From_blender -blender From_blender\TRAMKONCOMkick_heavy.xml
The TRAMKONCOMkick_heavy.xml links to the TRAMKONCOMkick_heavy.dae from Blender which needs to be in the same location as the .xml file.

==Poses==
===Oni's default orientation===
This pose, where the body parts are all at zero rotation, is usually referred to in the community as the "folded pose". 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, in the default pose, you can see the "true" translations (offsets) 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===
[[Image:Konoko_bodyparts.png|thumbnail|right|283px]]
Supplying the '''-noanim''' switch to OniSplit yields the "standing at attention" pose, a much less visually awkward pose than the default "folded pose". Note that "-noanim" goes in between the destination directory and the source file name:
:'''onisplit -extract:dae modelOutput/ -noanim ONCCkonoko_generic.oni'''

The result will look something the picture on the right, but the model will have her legs together and her arms by her side.

To produce this pose, these rotations are used:
:(0,90,90) for the pelvis
:(0,180,0) for both thighs
:(90,90,90) for the left shoulder
:(-90,-90,90) for the right shoulder
:(0,90,0) for the left biceps
:(0,-90,0) for the right biceps
:(-90,0,0) for the left hand/fist
:(90,0,0) for the right hand/fist
:(0,0,0) for all other parts
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.

===Idle pose===
If you use '''-extract:dae TargetFolder ONCCkonoko_generic.oni''', taking care that you have the TRAC/TRAM files next to the ONCC, OniSplit will look up the idle animation from the ONCC's TRAC and apply the rotations from the first frame of the animation 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 "folded" orientation or the "at attention" '''-noanim''' pose. A frame from 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 try==
===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:
#take two Oni characters (for simplicity, two characters who use the same skeleton: e.g., the Konokos from {{C|13}} and {{C|10}})
#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")
#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)
#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:
#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).
#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.
#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.
#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).
#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.
#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.
#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. ([[User:geyser|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. [[User:Geyser|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====
{|align=right
|http://geyser.oni2.net/edition/characters/gally/GLB_shot.png
|}
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 picture on the right);
*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 <strike>bitch</strike> 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 [http://geyser.oni2.net/edition/characters/gally/GLB_ripped.zip HERE] (well, not really as-is; I roundtripped it through 3D Exploration)
#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.
#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.
#There is a bunch of basic things that you want to do before actually adapting this character for Oni
##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 [http://geyser.oni2.net/edition/characters/gally/GLB_merged.zip THIS]. Reimport it into a new scene, and see what changed.
##Don't mind the "bone" objects for now. I just happened to include them in the rip, but I'm not sure why.
##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.
#Now you want to split the body mesh (part 18) into three parts and to add some placeholder meshes for the shoulders.
##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.
##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.
##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)
##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.
##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.
#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 [http://geyser.oni2.net/edition/characters/gally/GLB_almost.zip 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).
#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.
##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.
##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.
##Rotate Konoko's arms and shoulders to match Gally's pose. Try (0, +-65, 180) for shoulders and (0, +-65, 0) for arms.
##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", then all the upper body will move 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.
##*[http://geyser.oni2.net/edition/characters/gally/GLB_compact.zip HERE] is what you should get. Don't laugh too hard, and instead look at how well I matched the centers of Konoko's body parts with the tips of Gally's "bones". The only thing that's wrong at this point is that the shoulder parts are too far from their centers, and may end up sticking out of Gally's chest or back. To fix this, you can move, scale and rotate those parts in any way you like. Just remember to "Freeze all transforms" when you're done, especially if you've used scaling.
#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.
#When the reparenting and matching is over, you should get something like [http://geyser.oni2.net/edition/characters/gally/GLB_matched.zip THIS]. You can check that everything is OK simply by enabling the drawing of centers (either with the "eye" menu of a viewport, or with the "Center" filter), and then by alternatively middle-clicking "pelvis" and "pelvis2" (this selects the whole tree of either Gally, which we are unsure about, or the "compact Konoko", which we know to be OK because we only tweaked her [[TRTA]] a bit). If the centers and the local axes look the same for both Gally and Konoko, then Gally is OK too.
#And that's it, we're done. Now select all of Gally's meshes (as a tree, with Ctrl+T or middle-click), export to Collada ("selection only"), import into Oni (DAE to TRBS, TGA to TXMP, ONCC from '''konoko_generic''' and TRMA from '''ninjabot_tx''') and it should Just Work. And indeed it does. [http://geyser.oni2.net/edition/characters/gally/GLB_ready.zip HERE] is the input and [http://geyser.oni2.net/edition/characters/gally/level0_GUNNM.zip HERE] is the Oni-ready plugin (Windows only).
#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.
#This can be done in well under an hour - if you don't have to type a tutorial as you go, that is. Once you get the hang of this, you can save some time by completely skipping the "compact Konoko" part, and placing the new character's centers directly where you want them -- especially if the pose is as simple as this one, and/or if the model comes with a skeleton, or very clear anatomy, such as a robot. Challenges such as the [[AE:Iron Demon]] or the [[AE:BGI|BGI]] troopers/mecha come readily to mind, and could both use a tutorial.

[[Category:Modding tutorials]]

Importing character models

2022-11-20T22:17:46Z

Delano762: /* Modding tools - Updated Blender and XSI, removed 3D Exploration and Meshlab */

This article covers the importing of new character models into Oni, but also how to export models from Oni. Generally speaking, you are going to want to use [[wikipedia:COLLADA|COLLADA]] as the "passthrough" format between your 3D program and Oni, as this is exactly what COLLADA was designed for. In this article, COLLADA is referred to as "Collada" (because who enjoys being shouted at?), or by ".dae file" (because that is the file suffix for COLLADA).

==Modding tools==
===OniSplit===
This is the program that we use to get models into and out of Oni. It is a command line tool. There are GUI wrappers for OniSplit that cover most of its functions (see [[Vago (tool)]], but modders sometimes have to call it from the command line (or use the direct command line input feature in a GUI) to take full advantage of OniSplit's abilities.

===3D programs===
====Blender====
[[Blender]] is the community's current 3D software of choice, allowing for 3D modeling, animating, and more.

Blender rocks when it comes to [[Lightmapping levels|lightmapping levels]]. 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]]).

====XSI====
Softimage XSI is a Windows-only 3D software that went discontinued in 2014, and [https://www.moddb.com/downloads/autodesk-softimage-mod-tool-75 a free version of it from 2008] used to to be the community's modding tool of choice before moving on to Blender. A number of Oni-related addons, tools and tutorials were developed for it can be still found and used. It has detailed documentation and is versatile, whether working with characters or levels, though highly obsolete.

===File converters===
====Autodesk FBX====
Check out {{AutodeskFBX}} (primarily the FBX converter) if your tool can reliably import/export FBX but has trouble with Collada.

==Basic importing and exporting==
===Exporting from Oni to Collada===
OniSplit allows you to export .dae files from both [[TRBS]] and [[ONCC]]. Though all the 3D data is in the TRBS, the textures are listed in the [[TRMA]] file, which is only visible from the ONCC, not the TRBS. Thus, if you want to use the textures while editing the model, convert the ONCC, not the TRBS, into Collada. The instructions below assume that you want the textured model, and thus illustrate how to export the ONCC.

First, you need to find the class name for the character you want to export. You can accomplish this by going into Oni, loading the level in which the desired character appears, and then enabling the shapeshifter cheat -- but you have to do this by turning on [[Developer Mode]], not by entering the "shapeshifter" cheat code, because the regular cheat code does not display the console output that you need. Once Dev Mode is on, press F8 until you reach the desired character. You should see the message "character class ''number'' '''''string'''''". The number is unimportant, but write down the string, because that is the class name which provides the basis for the names of the ONCC and TRBS.

In this example, we'll export one of Konoko's models. For Konoko, we don't even need to open Oni to find the name of an ONCC because we have [[Konoko#In-game_outfits|this handy table]]. Let's use Konoko in her police uniform; you can see from the table that this is ONCCk3 and that it's found in level2_Final.

Next, you need to decide on the pose in which your character will be exported. See the "Poses" section below for guidance. Without making this example more complicated, we only have two choices for pose: default (folded) and -noanim (standing at attention); we are going to use the second option, for a more visually pleasing result. Here are the steps for getting your desired character in .dae format. Substitute backward slashes for forward ones if you are in Windows.

:1. Create a couple of folders in a convenient place. One folder will receive a whole bunch of files, and the second folder will hold the exported model. We'll call these paths "splitOutput/" and "modelOutput/" respectively.
:2. On the command line, go to the directory "Oni/GameDataFolder/", where "Oni/" means the path to your game.
:3. Split the desired level's data into its component resources with OniSplit. Where you see just "onisplit" in the following commands, you should take that to mean "C:\path\to\OniSplit.exe" in Windows or "mono /path/to/OniSplit.exe" on Macs (Mono is a third-party package that you need to run .NET applications in macOS):
::<tt>onisplit -export splitOutput/ level2_Final.dat</tt>
:4. Convert the desired character's model data into Collada:
::<tt>onisplit -extract:dae modelOutput/ -noanim splitOutput/ONCCk3.oni</tt>

This will create the file '''ONCCk3.dae''', and its supporting textures in TGA format, in modelOutput/. Note that only the highest level of detail (LOD) model will be exported using this method. See [[XML:TRBS]] for a method which exports all 5 LOD models.

Note that if you want to extract the model with a pose besides folded or -noanim, you need to have the animation data (the [[TRAC]] and [[TRAM]] .oni files) in the same folder as the model data (the ONCC and its related files). In vanilla (un-modded) Oni, animations for many characters (including Konoko) are only in level0_Final, and, as you saw above, model data is found in whichever level that character appears in. Extracting a model in the pose of your choice will be simpler if you have the [[AE]] installed, as it globalizes character data, placing it all in the level0_Final files in the AE's GameDataFolder. With vanilla Oni, you will have to split both level0_Final and level''x''_Final and then combine their files into one folder before you can perform the "-extract:dae" operation using the "-anim" tag that is discussed below.

===Importing from Collada into Oni===
When importing characters, the simplest method is to generate a whole body set ([[TRBS]]) from one .dae file. To convert your 3D model, let's say that you saved it in Collada format with the name "TRBSnewchar.dae". Run the command:
:<tt>onisplit -create:trbs DAEtoONI/ TRBSnewchar.dae</tt>

This will create '''TRBSnewchar.oni''' in the folder DAEtoONI. Because it was created from a single .dae file, this TRBS will contain 5 identical models for the 5 levels of detail (LOD) that Oni supports for each character. You have to import by XML in order to specify a different .dae for every LOD; see [[XML:TRBS]] for more info.

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 if you were editing a model exported from Oni). Possibly a future version of OniSplit can automatically generate a TRMA and TXMPs if the .dae file has textures.

Note that your file should be named appropriately if you want it to be looked up by name from one or more of Oni's existing ONCCs, or a new one of your own creation.

To actually test the model in-game, you should [[Making a mod package|create a mod package]] for it, place the package in Oni/AE/packages/, and select it in the AE Installer. The older method of testing your work is to rebuild the level by running "onisplit -import" on a folder containing your TRBS and all the other .oni files for a level, but this only creates a set of level files that you can use on your computer, and is inherently a disorganized approach to keeping track of your work. Creating an AE package will allow you to share your work with other players.

Please note that a final character mod package should contain multiple LOD models for your character. Filling all 5 slots with distinct models is not necessary; many modders create only two or three LOD models and fill the lower LOD slots with the simpler model(s) and the highest slot with the full-detail model, e.g.:
:# TRBSnewchar_low.dae
:# TRBSnewchar_low.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_mid.dae
:# TRBSnewchar_high.dae

An ONCC contains much more information than just links to TRBS and TRMA, and thus can not be generated automatically. See [[XML:ONCC]] on how to create such a file, and then import the character with this class data into Oni. The easiest way to try out an imported character in Oni is to name your imported TRBS so that it replaces an existing one and no ONCC editing is needed. The next step up is to clone an existing ONCC (in XML) and modify it to link to your new TRBS file(s).

==Poses==
===Oni's default orientation===
This pose, where the body parts are all at zero rotation, is usually referred to in the community as the "folded pose". 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, in the default pose, you can see the "true" translations (offsets) 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===
[[Image:Konoko_bodyparts.png|thumbnail|right|283px]]
Supplying the '''-noanim''' switch to OniSplit yields the "standing at attention" pose, a much less visually awkward pose than the default "folded pose". Note that "-noanim" goes in between the destination directory and the source file name:
:'''onisplit -extract:dae modelOutput/ -noanim ONCCkonoko_generic.oni'''

The result will look something the picture on the right, but the model will have her legs together and her arms by her side.

To produce this pose, these rotations are used:
:(0,90,90) for the pelvis
:(0,180,0) for both thighs
:(90,90,90) for the left shoulder
:(-90,-90,90) for the right shoulder
:(0,90,0) for the left biceps
:(0,-90,0) for the right biceps
:(-90,0,0) for the left hand/fist
:(90,0,0) for the right hand/fist
:(0,0,0) for all other parts
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.

===Idle pose===
If you use '''-extract:dae TargetFolder ONCCkonoko_generic.oni''', taking care that you have the TRAC/TRAM files next to the ONCC, OniSplit will look up the idle animation from the ONCC's TRAC and apply the rotations from the first frame of the animation 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 "folded" orientation or the "at attention" '''-noanim''' pose. A frame from 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 try==
===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:
#take two Oni characters (for simplicity, two characters who use the same skeleton: e.g., the Konokos from {{C|13}} and {{C|10}})
#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")
#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)
#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:
#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).
#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.
#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.
#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).
#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.
#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.
#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. ([[User:geyser|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. [[User:Geyser|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====
{|align=right
|http://geyser.oni2.net/edition/characters/gally/GLB_shot.png
|}
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 picture on the right);
*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 <strike>bitch</strike> 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 [http://geyser.oni2.net/edition/characters/gally/GLB_ripped.zip HERE] (well, not really as-is; I roundtripped it through 3D Exploration)
#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.
#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.
#There is a bunch of basic things that you want to do before actually adapting this character for Oni
##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 [http://geyser.oni2.net/edition/characters/gally/GLB_merged.zip THIS]. Reimport it into a new scene, and see what changed.
##Don't mind the "bone" objects for now. I just happened to include them in the rip, but I'm not sure why.
##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.
#Now you want to split the body mesh (part 18) into three parts and to add some placeholder meshes for the shoulders.
##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.
##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.
##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)
##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.
##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.
#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 [http://geyser.oni2.net/edition/characters/gally/GLB_almost.zip 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).
#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.
##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.
##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.
##Rotate Konoko's arms and shoulders to match Gally's pose. Try (0, +-65, 180) for shoulders and (0, +-65, 0) for arms.
##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", then all the upper body will move 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.
##*[http://geyser.oni2.net/edition/characters/gally/GLB_compact.zip HERE] is what you should get. Don't laugh too hard, and instead look at how well I matched the centers of Konoko's body parts with the tips of Gally's "bones". The only thing that's wrong at this point is that the shoulder parts are too far from their centers, and may end up sticking out of Gally's chest or back. To fix this, you can move, scale and rotate those parts in any way you like. Just remember to "Freeze all transforms" when you're done, especially if you've used scaling.
#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.
#When the reparenting and matching is over, you should get something like [http://geyser.oni2.net/edition/characters/gally/GLB_matched.zip THIS]. You can check that everything is OK simply by enabling the drawing of centers (either with the "eye" menu of a viewport, or with the "Center" filter), and then by alternatively middle-clicking "pelvis" and "pelvis2" (this selects the whole tree of either Gally, which we are unsure about, or the "compact Konoko", which we know to be OK because we only tweaked her [[TRTA]] a bit). If the centers and the local axes look the same for both Gally and Konoko, then Gally is OK too.
#And that's it, we're done. Now select all of Gally's meshes (as a tree, with Ctrl+T or middle-click), export to Collada ("selection only"), import into Oni (DAE to TRBS, TGA to TXMP, ONCC from '''konoko_generic''' and TRMA from '''ninjabot_tx''') and it should Just Work. And indeed it does. [http://geyser.oni2.net/edition/characters/gally/GLB_ready.zip HERE] is the input and [http://geyser.oni2.net/edition/characters/gally/level0_GUNNM.zip HERE] is the Oni-ready plugin (Windows only).
#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.
#This can be done in well under an hour - if you don't have to type a tutorial as you go, that is. Once you get the hang of this, you can save some time by completely skipping the "compact Konoko" part, and placing the new character's centers directly where you want them -- especially if the pose is as simple as this one, and/or if the model comes with a skeleton, or very clear anatomy, such as a robot. Challenges such as the [[AE:Iron Demon]] or the [[AE:BGI|BGI]] troopers/mecha come readily to mind, and could both use a tutorial.

[[Category:Modding tutorials]]

OniSplit

2022-11-20T21:55:21Z

Delano762: /* Commands - added Blender support */

{{TOCfloat|side=right}}
{{Hatnote|Before reading this page, it's a good idea to be familiar with basic Oni [[game data terminology]].}}
'''OniSplit''', written by [[User_talk:Neo|Neo]], is an integral part of the [[Anniversary Edition]] and an essential modding tool on its own. It is a command line tool which can import and export almost all kinds of Oni game data, including textures, sound, 3D models, level geometry and combat animations. Its name comes from its original purpose, which was breaking Oni's level data files into individual resources. Later, the ability to convert those resources' data between Oni's format and standard file formats was added. OniSplit incorporates the latest [[OBD|knowledge about Oni's game data]], and it is currently the community's main modding tool.

:''Subpages:'' [[/Change_log|Change log]] (past versions), [[/WIP|WIP notes]] (upcoming versions)

==Getting it==
===Download links===
* Latest release of OniSplit: [http://mods.oni2.net/node/38 v0.9.99.2] ([http://websvn.illy.bz/dl.php?repname=Oni2&path=%2FOniSplit%2F&isdir=1 source code])
* The current GUI for OniSplit is [[Vago (tool)|Vago]]. '''You should try the GUI to see if it does what you need before working with OniSplit on the command line.'''

===Requirements===
*Windows: [https://dotnet.microsoft.com/en-us/download/dotnet-framework .NET framework]
*macOS: [https://www.mono-project.com/download/stable/ Mono framework]

==Workflow==
OniSplit is used in up to four different stages when modding:
{|
|rowspan="2"|'''OUT'''
|''Exporting'' - using the <tt>-export</tt> command, a [[Dat|level data file]] is broken into its component resources, .oni files.
|-
|style="border-style: solid; border-width: 0 0 1px 0"|''Extracting'' - using the <tt>-extract</tt> commands, .oni files are converted to standard-format files that can be edited in various third-party programs.
|-
|rowspan="2"|<center>'''IN'''</center>
|''Creating'' - using the <tt>-create</tt> commands, standard-format files are converted into .oni files.
|-
|''Importing'' - using the <tt>-import</tt> command, a folder of .oni files is combined into a level data file.
|}

Note that "extracting" refers to a conversion from one format to another, but "exporting" only refers to the creation of .oni files from a .dat file. When exporting, no conversion or re-formatting is taking place; the data is simply being copied out of a .dat (any connected binary data in .raw/.sep files will be concatenated to the data from the .dat when making the .oni).

==Beginner's tips==
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
In Windows, there are several options through which you can use OniSplit - out of which it is recommended to get Vago and CMDer:
* [[Vago (tool)|Vago]] is a GUI for OniSplit which allows you to handle all general conversions, save your sessions as project files, input manual commands if needed, and more. The two downsides of it is that it doesn't support Blender yet, forcing the users input commands manually, which in turn are not stored upon ending the session.
* [https://cmder.app/ CMDer] is an excellent alternative to cmd.exe. It can be customized to allow starting it from any folder you pick with the context menu, and it also stores the most recently used commands after ending the session. Currently it is highly useful for Blender-related operations.
* Command Prompt/cmd.exe. Windows' default command line interpreter, it's a poor choice as it does not store most recently used commands.

On Macs, the command line is found in the Terminal app (/Applications/Utilities) (press Command-Spacebar and type "Terminal" to get there faster).

===OniSplit syntax===
The basic syntax is:
{|
|-
|'''Windows'''||<tt>OniSplit.exe -create:trbs C:\Games\Oni\SomeFolder -normals C:\Games\Oni\Modding\TRBSMyNewChar.dae</tt>
|-
|'''Mac'''||<tt>mono OniSplit.exe -create:trbs /Games/Oni/SomeFolder -normals /Games/Oni/Modding/TRBSMyNewChar.dae</tt>
|}

Here's how it breaks down:
{|
! style="width:130px"|
|- valign="top"
|'''Invocation'''
|Windows can refer to the program directly, but Macs use Mono to run the .NET app; note also that if OniSplit.exe is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.
|-
|'''Option'''||The command.
|- valign="top"
|'''Path to folder'''||Whether destination or source, the path which is a folder comes first. Use the full path to the folder (starting from "C:\", or "/" on Macs).
|-
|'''Option flags'''||The flags that can optionally go with this command, separated by spaces.
|- valign="top"
|'''Path to file'''||Whether destination or source, the path of the file comes second. Use the full path to the file (starting from "C:\", or "/" on Macs). One exception to this parameter being a file is when using <tt>-create</tt> to make a level, in which case this is where you supply the source folder.
|}

===CLI tips===
*Command line interfaces (CLI) usually supply an auto-complete feature to save on typing. If you've typed enough of a file/folder name to identify it, press the Tab key and the rest should fill in. In Windows, you may not get the right path name autocompleted on the first try if there are multiple possible autocompletions based on the names in that directory, so keep pressing Tab to cycle through all possibilities. On Macs, if you have not typed enough of the name to narrow it down to a single autocompletion, you will hear an error sound. Double-tap Tab to see a list of possible autocompletions, then keep typing until you have narrowed it down to one of those and then hit Tab to fill in the rest of its name.

*Note that you can also drag files/folders into the window and the path will magically appear; in cases where you don't need to use a wildcard, this is the fastest way to build an OniSplit command.

===Wildcards===
Wildcards can be used to supply patterns to CLI programs. The wildcard is simply the <tt>*</tt> character. For instance:
OniSplit.exe -export:TRAM* <destination> <source .dat>
will export all the TRAMs in the source .dat into the destination folder. Using "TRAMKON*" would export all of Konoko's animations.

===Spaces in paths===
Command line interfaces (CLI) do not recognize spaces as a possible part of a path name because spaces are what separate the terms in your commands. The best course of action is to not use paths with spaces in their names! But if you must, you can use quotes to tell the CLI that a certain string is a single path:

'''C:\Games\Oni\>'''OniSplit.exe -list "My Mod Folder\level5_Final.dat"

This works in the Mac Terminal too, but you can also use the escape character, <tt>\</tt>. Also, other characters like <tt>(</tt> need to be escaped as well if you do not use quotes:

'''MyMac%''' mono OniSplit.exe -list My\ Mods\ \(In\ Progress\)/level5_Final.dat

But as mentioned, the best practice is to not use any characters besides the alphabet and numbers. It makes your life simpler, and if you ask for help on the forum with a command, no one wants to have to read your long path with lots of spaces or escaped characters in it ;-)

===Reading the commands below===
*The following commands should be complete, but the current list can be obtained by calling OniSplit with the <tt>-help</tt> option. You should also use <tt>-version</tt> to make sure you're using the latest version, the number of which is given in the "Download links" section above.

*Sample usages are given after certain commands. These are in DOS style, so if you are on a Mac, simply flip the <tt>\</tt>s to <tt>/</tt>s and make "C:\" into a leading "/".

*Optional flags are listed in square brackets simply to indicate that they're optional; don't enter the brackets when typing a command.

Note that only the .dat file from a level's data files is mentioned. The .raw and .sep files will be accessed by OniSplit as necessary when working with the .dat file that you gave the name of.
{{Divhide|end}}

==Commands==
===Conversion between .dat and .oni===
{|
! style="width:430px"|
|-
|<code>-list <file name></code>||Lists the named resources contained in a .dat (see [[OBD:File_types/Named|HERE]] for info on unnamed resources)
|-
|<code>-export <destination directory> <dat file></code>||Breaks .dat file into .oni files
|-
|<code>-export:<pattern> <destination directory> <dat file></code>||Exports named resource (wildcards also allowed) from .dat file
|- valign="top"
|<code>-import <source directory> <new dat file></code>||Compiles level files from source directory using the name you supply for the .dat file; tries to get target file format from source SNDD, but it's better to use the :sep or :nosep variants below
|-
|colspan="2"|To create level5_Final.dat/.raw[/.sep] from the files in MyNewLevel\: <code>OniSplit.exe -import C:\Oni\MyNewLevel\ C:\Oni\GameDataFolder\level5_Final.dat</code>
|-
|<code>-import:sep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw/.sep format (Mac and PC Demo)
|-
|<code>-import:nosep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw format (PC retail)
|}
:Note that <tt>-import</tt> will search subdirectories too. If you find having hundreds or thousand of files .oni in one directory to be unmanageable you can always group them in subdirectories any way you like. The only exception is that a subdirectory named "noimport" or "_noimport" is always ignored.

===Management of .oni files===
Sometimes you want to move some .oni files out of a larger folder of .onis. You could do this manually, but OniSpit knows which files depend on others. It will also look for those dependencies in subfolders beneath the level of the file you supply the name of. The filename field supports wildcards. This is mostly used by the [[AE]] Installer rather than modders themselves.
{|
|<code>-deps <oni file></code>||Displays a list of .oni files that the specified .oni file depends on
|-
|<code>-copy <destination directory> <oni file></code>||Copies .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move <destination directory> <oni file></code>||Moves an .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move:overwrite <destination directory> <oni file></code>||Moves an .oni file and its dependencies; overwrites any existing .oni files
|-
|<code>-move:delete <destination directory> <oni file></code>||Moves an .oni file and its dependencies; doesn't overwrite; deletes source files
|}

===Conversion between .oni/.dat and 3rd party formats===
====Textures====
Unless mentioned otherwise, source filenames support wildcards. See [[Modifying textures|HERE]] for a detailed tutorial. The <tt>-extract</tt> commands can work with .oni files (a single file or several files if you use the wildcard), or rip all the TXMPs from a .dat file.
{|
|<code>-extract:dds <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into DDS files
|-
|<code>-extract:tga <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into TGA files
|-
|<code>-extract:png <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into PNG files
|-
|<code>-create:txmp <destination directory> [-genmipmaps] [-nouwrap] [-novwrap] <nowiki>[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]</nowiki> [-envmap:texture_name] <image file></code>
|valign=top|Creates .oni file from image file (PNG, TGA, or DDS)
|}

====Models====
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can be exported to the Wavefront .obj and COLLADA .dae formats. For details see [[Importing character models]] and [[Importing weapon models]]. The generic <tt>-extract</tt> commands can work with .oni files (a single file, or several files if you use the wildcard), or rip all the TXMP from a .dat file. TRBS and ONCC support additional <tt>-noanim</tt> and <tt>-anim</tt> options for <tt>-extract:dae</tt>; see [[Importing character models]] for details. Imported geometry must only contain triangles.
{|
! style="width:540px"|
|- valign="top"
|<code>-extract:obj <destination directory> <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Wavefront OBJ files
|- valign="top"
|<code>-extract:dae <destination directory> [-noanim] <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Collada DAE files
|-
|<code>-create:m3gm <destination directory> [-tex:texture_name] <OBJ file></code>||Creates a M3GM .oni from an .obj file
|-
|<code>-create:trbs <destination directory> [-cel] [-normals] <DAE file></code>||Creates a TRBS .oni from a .dae file
|}

Note on -noanim parameter: Normally OniSplit exports the character with an idle animation. If you use -noanim the character is exported in "I" pose, also the pelvis has the coordinates x=0, y=0, z=0.

====Levels====
OniSplit can convert AKEV files (level geometry) and the associated file types to and from DAE format:
{|
|<code>-extract:dae <destination directory> <AKEV.oni file></code>||Extracts 3D data in AKEV and related resources from dependencies into Collada file
|}

The next two steps are used on a folder in which you have placed the DAE and XML-formatted instances of the required files, as well as textures in TGA format. See [http://oni.bungie.org/forum/viewtopic.php?id=1515 HERE] for details.
{|
|- valign="top"
|<code>-create <destination directory> [-genmipmaps] [-format:dxt1] <source directory></code>||Converts all AKEV and related instances to .oni files
|- valign="top"
|<code>-import:nosep <source directory> <target file name>.dat</code>||The standard command for creating .dat/.raw files from .oni files (remember to use the import:sep option on Mac!)
|}

====Sounds====
The sounds in Windows Oni are stored in WAV format, and on Macs are stored in AIFF format. This also means creating each of your SNDD files in both formats in order to work on both platforms.
{|
|<code>-extract:wav <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .wav files
|-
|<code>-extract:aif <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .aif files
|}

====Text====
{|
|<code>-extract:txt <destination directory> <dat/oni file></code>||Rips text data from a SUBT .oni file (or all SUBTs from a .dat) as .txt files
|-
|<code>-create:subt <destination directory> <TXT file></code>||Creates a SUBT .oni file from a .txt file
|}

====XML====
One of the latest features is conversion of .oni files to and from an XML file, or an XML metafile and related 3rd-party format files. XML files are easier to read and edit.
::Currently XML export/import is limited to files that do not have raw/sep parts. 2-way conversion is known to work for [[BINA]], [[CONS]], [[DOOR]], [[DPge]], [[FILM]], [[HPge]], [[IGHH]], [[IPge]], [[M3GM]], [[OBAN]], [[ONCC]], [[ONCV]], [[ONLD]], [[ONLV]], [[ONGS]], [[ONSK]], [[ONVL]], [[ONWC]], [[OPge]], [[OSBD]], [[PSpc]], [[PSpL]], [[PSUI]], [[TRAC]], [[TRAM]], [[TRIG]], [[TRGE]], [[TRMA]], [[TRSC]], [[TXMB]], [[TXMP]], [[WMCL]], [[WMDD]], [[WMM_]], [[WPge]].
:::For detailed examples and tutorials, see [[XML|HERE]]
{|
|<code>-extract:xml <destination directory> <oni file></code>||Extracts .oni file and all related resources to XML files and 3rd-party formats
|-
|<code>-create <destination directory> <XML file></code>||Creates an .oni file from an XML file
|}

====Blender support====
[[Blender]] by default has a number of issues with most of Oni's assets, however, OniSplit allows exporting them to Blender-readable files with the <tt>-blender</tt> flag.

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]][[Category:Modding tutorials]]

OniSplit

2022-11-20T21:42:47Z

Delano762: /* Beginner's tips - recommended Vago and CMDer*/

{{TOCfloat|side=right}}
{{Hatnote|Before reading this page, it's a good idea to be familiar with basic Oni [[game data terminology]].}}
'''OniSplit''', written by [[User_talk:Neo|Neo]], is an integral part of the [[Anniversary Edition]] and an essential modding tool on its own. It is a command line tool which can import and export almost all kinds of Oni game data, including textures, sound, 3D models, level geometry and combat animations. Its name comes from its original purpose, which was breaking Oni's level data files into individual resources. Later, the ability to convert those resources' data between Oni's format and standard file formats was added. OniSplit incorporates the latest [[OBD|knowledge about Oni's game data]], and it is currently the community's main modding tool.

:''Subpages:'' [[/Change_log|Change log]] (past versions), [[/WIP|WIP notes]] (upcoming versions)

==Getting it==
===Download links===
* Latest release of OniSplit: [http://mods.oni2.net/node/38 v0.9.99.2] ([http://websvn.illy.bz/dl.php?repname=Oni2&path=%2FOniSplit%2F&isdir=1 source code])
* The current GUI for OniSplit is [[Vago (tool)|Vago]]. '''You should try the GUI to see if it does what you need before working with OniSplit on the command line.'''

===Requirements===
*Windows: [https://dotnet.microsoft.com/en-us/download/dotnet-framework .NET framework]
*macOS: [https://www.mono-project.com/download/stable/ Mono framework]

==Workflow==
OniSplit is used in up to four different stages when modding:
{|
|rowspan="2"|'''OUT'''
|''Exporting'' - using the <tt>-export</tt> command, a [[Dat|level data file]] is broken into its component resources, .oni files.
|-
|style="border-style: solid; border-width: 0 0 1px 0"|''Extracting'' - using the <tt>-extract</tt> commands, .oni files are converted to standard-format files that can be edited in various third-party programs.
|-
|rowspan="2"|<center>'''IN'''</center>
|''Creating'' - using the <tt>-create</tt> commands, standard-format files are converted into .oni files.
|-
|''Importing'' - using the <tt>-import</tt> command, a folder of .oni files is combined into a level data file.
|}

Note that "extracting" refers to a conversion from one format to another, but "exporting" only refers to the creation of .oni files from a .dat file. When exporting, no conversion or re-formatting is taking place; the data is simply being copied out of a .dat (any connected binary data in .raw/.sep files will be concatenated to the data from the .dat when making the .oni).

==Beginner's tips==
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
In Windows, there are several options through which you can use OniSplit - out of which it is recommended to get Vago and CMDer:
* [[Vago (tool)|Vago]] is a GUI for OniSplit which allows you to handle all general conversions, save your sessions as project files, input manual commands if needed, and more. The two downsides of it is that it doesn't support Blender yet, forcing the users input commands manually, which in turn are not stored upon ending the session.
* [https://cmder.app/ CMDer] is an excellent alternative to cmd.exe. It can be customized to allow starting it from any folder you pick with the context menu, and it also stores the most recently used commands after ending the session. Currently it is highly useful for Blender-related operations.
* Command Prompt/cmd.exe. Windows' default command line interpreter, it's a poor choice as it does not store most recently used commands.

On Macs, the command line is found in the Terminal app (/Applications/Utilities) (press Command-Spacebar and type "Terminal" to get there faster).

===OniSplit syntax===
The basic syntax is:
{|
|-
|'''Windows'''||<tt>OniSplit.exe -create:trbs C:\Games\Oni\SomeFolder -normals C:\Games\Oni\Modding\TRBSMyNewChar.dae</tt>
|-
|'''Mac'''||<tt>mono OniSplit.exe -create:trbs /Games/Oni/SomeFolder -normals /Games/Oni/Modding/TRBSMyNewChar.dae</tt>
|}

Here's how it breaks down:
{|
! style="width:130px"|
|- valign="top"
|'''Invocation'''
|Windows can refer to the program directly, but Macs use Mono to run the .NET app; note also that if OniSplit.exe is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.
|-
|'''Option'''||The command.
|- valign="top"
|'''Path to folder'''||Whether destination or source, the path which is a folder comes first. Use the full path to the folder (starting from "C:\", or "/" on Macs).
|-
|'''Option flags'''||The flags that can optionally go with this command, separated by spaces.
|- valign="top"
|'''Path to file'''||Whether destination or source, the path of the file comes second. Use the full path to the file (starting from "C:\", or "/" on Macs). One exception to this parameter being a file is when using <tt>-create</tt> to make a level, in which case this is where you supply the source folder.
|}

===CLI tips===
*Command line interfaces (CLI) usually supply an auto-complete feature to save on typing. If you've typed enough of a file/folder name to identify it, press the Tab key and the rest should fill in. In Windows, you may not get the right path name autocompleted on the first try if there are multiple possible autocompletions based on the names in that directory, so keep pressing Tab to cycle through all possibilities. On Macs, if you have not typed enough of the name to narrow it down to a single autocompletion, you will hear an error sound. Double-tap Tab to see a list of possible autocompletions, then keep typing until you have narrowed it down to one of those and then hit Tab to fill in the rest of its name.

*Note that you can also drag files/folders into the window and the path will magically appear; in cases where you don't need to use a wildcard, this is the fastest way to build an OniSplit command.

===Wildcards===
Wildcards can be used to supply patterns to CLI programs. The wildcard is simply the <tt>*</tt> character. For instance:
OniSplit.exe -export:TRAM* <destination> <source .dat>
will export all the TRAMs in the source .dat into the destination folder. Using "TRAMKON*" would export all of Konoko's animations.

===Spaces in paths===
Command line interfaces (CLI) do not recognize spaces as a possible part of a path name because spaces are what separate the terms in your commands. The best course of action is to not use paths with spaces in their names! But if you must, you can use quotes to tell the CLI that a certain string is a single path:

'''C:\Games\Oni\>'''OniSplit.exe -list "My Mod Folder\level5_Final.dat"

This works in the Mac Terminal too, but you can also use the escape character, <tt>\</tt>. Also, other characters like <tt>(</tt> need to be escaped as well if you do not use quotes:

'''MyMac%''' mono OniSplit.exe -list My\ Mods\ \(In\ Progress\)/level5_Final.dat

But as mentioned, the best practice is to not use any characters besides the alphabet and numbers. It makes your life simpler, and if you ask for help on the forum with a command, no one wants to have to read your long path with lots of spaces or escaped characters in it ;-)

===Reading the commands below===
*The following commands should be complete, but the current list can be obtained by calling OniSplit with the <tt>-help</tt> option. You should also use <tt>-version</tt> to make sure you're using the latest version, the number of which is given in the "Download links" section above.

*Sample usages are given after certain commands. These are in DOS style, so if you are on a Mac, simply flip the <tt>\</tt>s to <tt>/</tt>s and make "C:\" into a leading "/".

*Optional flags are listed in square brackets simply to indicate that they're optional; don't enter the brackets when typing a command.

Note that only the .dat file from a level's data files is mentioned. The .raw and .sep files will be accessed by OniSplit as necessary when working with the .dat file that you gave the name of.
{{Divhide|end}}

==Commands==
===Conversion between .dat and .oni===
{|
! style="width:430px"|
|-
|<code>-list <file name></code>||Lists the named resources contained in a .dat (see [[OBD:File_types/Named|HERE]] for info on unnamed resources)
|-
|<code>-export <destination directory> <dat file></code>||Breaks .dat file into .oni files
|-
|<code>-export:<pattern> <destination directory> <dat file></code>||Exports named resource (wildcards also allowed) from .dat file
|- valign="top"
|<code>-import <source directory> <new dat file></code>||Compiles level files from source directory using the name you supply for the .dat file; tries to get target file format from source SNDD, but it's better to use the :sep or :nosep variants below
|-
|colspan="2"|To create level5_Final.dat/.raw[/.sep] from the files in MyNewLevel\: <code>OniSplit.exe -import C:\Oni\MyNewLevel\ C:\Oni\GameDataFolder\level5_Final.dat</code>
|-
|<code>-import:sep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw/.sep format (Mac and PC Demo)
|-
|<code>-import:nosep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw format (PC retail)
|}
:Note that <tt>-import</tt> will search subdirectories too. If you find having hundreds or thousand of files .oni in one directory to be unmanageable you can always group them in subdirectories any way you like. The only exception is that a subdirectory named "noimport" or "_noimport" is always ignored.

===Management of .oni files===
Sometimes you want to move some .oni files out of a larger folder of .onis. You could do this manually, but OniSpit knows which files depend on others. It will also look for those dependencies in subfolders beneath the level of the file you supply the name of. The filename field supports wildcards. This is mostly used by the [[AE]] Installer rather than modders themselves.
{|
|<code>-deps <oni file></code>||Displays a list of .oni files that the specified .oni file depends on
|-
|<code>-copy <destination directory> <oni file></code>||Copies .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move <destination directory> <oni file></code>||Moves an .oni file and its dependencies; skips file if it already exists at destination
|-
|<code>-move:overwrite <destination directory> <oni file></code>||Moves an .oni file and its dependencies; overwrites any existing .oni files
|-
|<code>-move:delete <destination directory> <oni file></code>||Moves an .oni file and its dependencies; doesn't overwrite; deletes source files
|}

===Conversion between .oni/.dat and 3rd party formats===
====Textures====
Unless mentioned otherwise, source filenames support wildcards. See [[Modifying textures|HERE]] for a detailed tutorial. The <tt>-extract</tt> commands can work with .oni files (a single file or several files if you use the wildcard), or rip all the TXMPs from a .dat file.
{|
|<code>-extract:dds <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into DDS files
|-
|<code>-extract:tga <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into TGA files
|-
|<code>-extract:png <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into PNG files
|-
|<code>-create:txmp <destination directory> [-genmipmaps] [-nouwrap] [-novwrap] <nowiki>[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]</nowiki> [-envmap:texture_name] <image file></code>
|valign=top|Creates .oni file from image file (PNG, TGA, or DDS)
|}

====Models====
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can be exported to the Wavefront .obj and COLLADA .dae formats. For details see [[Importing character models]] and [[Importing weapon models]]. The generic <tt>-extract</tt> commands can work with .oni files (a single file, or several files if you use the wildcard), or rip all the TXMP from a .dat file. TRBS and ONCC support additional <tt>-noanim</tt> and <tt>-anim</tt> options for <tt>-extract:dae</tt>; see [[Importing character models]] for details. Imported geometry must only contain triangles.
{|
! style="width:540px"|
|- valign="top"
|<code>-extract:obj <destination directory> <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Wavefront OBJ files
|- valign="top"
|<code>-extract:dae <destination directory> [-noanim] <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Collada DAE files
|-
|<code>-create:m3gm <destination directory> [-tex:texture_name] <OBJ file></code>||Creates a M3GM .oni from an .obj file
|-
|<code>-create:trbs <destination directory> [-cel] [-normals] <DAE file></code>||Creates a TRBS .oni from a .dae file
|}

Note on -noanim parameter: Normally OniSplit exports the character with an idle animation. If you use -noanim the character is exported in "I" pose, also the pelvis has the coordinates x=0, y=0, z=0.

====Levels====
OniSplit can convert AKEV files (level geometry) and the associated file types to and from DAE format:
{|
|<code>-extract:dae <destination directory> <AKEV.oni file></code>||Extracts 3D data in AKEV and related resources from dependencies into Collada file
|}

The next two steps are used on a folder in which you have placed the DAE and XML-formatted instances of the required files, as well as textures in TGA format. See [http://oni.bungie.org/forum/viewtopic.php?id=1515 HERE] for details.
{|
|- valign="top"
|<code>-create <destination directory> [-genmipmaps] [-format:dxt1] <source directory></code>||Converts all AKEV and related instances to .oni files
|- valign="top"
|<code>-import:nosep <source directory> <target file name>.dat</code>||The standard command for creating .dat/.raw files from .oni files (remember to use the import:sep option on Mac!)
|}

====Sounds====
The sounds in Windows Oni are stored in WAV format, and on Macs are stored in AIFF format. This also means creating each of your SNDD files in both formats in order to work on both platforms.
{|
|<code>-extract:wav <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .wav files
|-
|<code>-extract:aif <destination directory> <dat/oni file></code>||Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .aif files
|}

====Text====
{|
|<code>-extract:txt <destination directory> <dat/oni file></code>||Rips text data from a SUBT .oni file (or all SUBTs from a .dat) as .txt files
|-
|<code>-create:subt <destination directory> <TXT file></code>||Creates a SUBT .oni file from a .txt file
|}

====XML====
One of the latest features is conversion of .oni files to and from an XML file, or an XML metafile and related 3rd-party format files. XML files are easier to read and edit.
::Currently XML export/import is limited to files that do not have raw/sep parts. 2-way conversion is known to work for [[BINA]], [[CONS]], [[DOOR]], [[DPge]], [[FILM]], [[HPge]], [[IGHH]], [[IPge]], [[M3GM]], [[OBAN]], [[ONCC]], [[ONCV]], [[ONLD]], [[ONLV]], [[ONGS]], [[ONSK]], [[ONVL]], [[ONWC]], [[OPge]], [[OSBD]], [[PSpc]], [[PSpL]], [[PSUI]], [[TRAC]], [[TRAM]], [[TRIG]], [[TRGE]], [[TRMA]], [[TRSC]], [[TXMB]], [[TXMP]], [[WMCL]], [[WMDD]], [[WMM_]], [[WPge]].
:::For detailed examples and tutorials, see [[XML|HERE]]
{|
|<code>-extract:xml <destination directory> <oni file></code>||Extracts .oni file and all related resources to XML files and 3rd-party formats
|-
|<code>-create <destination directory> <XML file></code>||Creates an .oni file from an XML file
|}

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]][[Category:Modding tutorials]]

Creating an animation rig in Blender

2022-05-21T17:05:16Z

Delano762: /* Overview of the rig */ clarified why do we have T-Pose, Pose 1 and Pose 2 collections in the rig

==Introduction==
This tutorial shows you how to create the [http://mods.oni2.net/node/388 animation rig for Blender] (made by geyser) from scratch, with some improvements.

The purpose of this rig is to give us much better tools to animate, compared to our [http://oni.bungie.org/forum/viewtopic.php?pid=23698#p23698 previous process in Softimage XSI] by EdT, which allowed us to animate exclusively with Forward Kinematics. While FK may work for simple, short animations done on characters with a small amount of bones, it does not work well for Oni characters and animations, as it's too labor-intensive and inefficient.

'''If you are looking for information on how to use the rig, please refer to the article on that available [[Using_the_Rigify_animation_rig|HERE.]]'''

==Prerequisite tutorials==
I highly recommend watching the tutorials below if you feel you're lacking knowledge in any of these subjects:

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins]

Blender Character Rigging overview showing that you can create a Rigify rig in less than a minute at 5:43, and also rig a character while at it:
* [https://youtu.be/f2pTkW-1JkE?t=343 Character Rigging - Blender 2.80 Fundamentals]

Practical and intuitive explanation of what Inverse and Forward Kinematics (IK/FK) are - this is explained in Maya, but same principles apply in every 3D editing program including Blender:
* [https://www.youtube.com/watch?v=p6PYKyxR0aY Animating with IK and FK]

Basics of using Rigify:
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify Tutorial #08 - Posing the Rigify rig] by CGDive

Rigify Bone Groups and Layers:
* [https://www.youtube.com/watch?v=5FK4jDCAOkk Rigify Tutorial 7-1: Rigify Bone Groups and Layers (Overview)] by CGDive
* [https://www.youtube.com/watch?v=JZZHCmKFcMs Rigify Tutorial 7-2: Rigify Bone Groups and Layers (Practice)] by CGDive
* [https://www.youtube.com/watch?v=2XldUB2eT-o Rigify Tutorial 7-3: Rigify Bone Groups and Layers (Advanced)] by CGDive

Changing Rigify Custom Shapes and Widgets:
* [https://www.youtube.com/watch?v=beVtWATcw9U Rigify - Custom Shapes/Widgets] by CGDive

Blender custom properties and '''drivers''' (drivers in the rig described here are used to set the influence of its controllers' bone constraints through the Pose1 and Pose2 bone locations):
* [https://www.youtube.com/watch?v=_197jQFh22E Custom properties and drivers in blender made easy] by Pierrick Picaut

===Tracking constraint tutorials===
These explain constraints like Damped Track which are used by Rigify – you can skip this if you want, but it might give you a better idea of how Rigify's MCH (Mechanical) layers work, or come in handy in the distant future; other than that, you don't need to know them to animate for Oni:
* [https://www.youtube.com/watch?v=aGBOu-dNZ-w Tracking Constraints - Blender 2.80 Fundamentals]
* [https://www.youtube.com/watch?v=5FK4jDCAOkk Camera Track To vs Damped Track Constraints | Pros & Cons Explained With Examples | Blender] by 5 minutes Blender

==Things to know before starting==
There are several things worth knowing before you start creating the rig.

===Tools and relevant tutorials===
[[Image:Cmder.png|200px|right|thumb|Screenshot showing Cmder's capabilities within the context of modding Oni]]
* [http://mods.oni2.net/node/38 '''Current version of OniSplit.'''] This is the tool needed to import and export assets out of Oni. '''DO NOT USE OniSplit GUI or Vago for importing Oni assets into Blender''' - neither of these weren't updated in a long time, and thus they don't support OniSplit's v0.9.99.2 -blender option. You can still use them for other purposes though, such as sounds and converting .oni files to XMLs, etc.
* [https://cmder.net/ '''Cmder'''] (Windows only) - because OniSplit is a command line tool, it is highly recommended to get any upgrade to Windows' Command Prompt. As shown in the screenshot on the right, Cmder allows you to start it from the context menu in any selected folder, and it also remembers your most recently used commands, vastly improving your workflow when you're forced to use any command line tools.
* [https://docs.blender.org/manual/en/2.81/addons/rigging/rigify.html '''Rigify'''] - it's a plugin for Blender designed to automate a lot of rigging work. The rig described here is generated using Rigify.
* [https://docs.google.com/document/d/175uJGklYASAgrFjxuUG4-kJRDoMTjjP7GvNxSj1GscU/edit '''Oni-Blender tutorial'''] by EdT. Please read this in entirety to know likely-to-happen issues and refer to this as your guide for OniSplit commands relating to Blender.
* [http://oni.bungie.org/forum/viewtopic.php?pid=23230#p23230 '''Brief overview on creating TRAMs'''] by EdT - while this was written with XSI in mind, this is still relevant as the process for preparing the XML files for Oni is still the same. Also the next post in that thread, called '''Brief walk through on modifying a TRAM,''' is an example of that overview put into practice.

===Assorted issues in Blender===
Please refer to [[Blender#Oni-specific_issues_with_Blender|THIS]] section of the "Blender" article for issues that you will run into while Oni modding.

==Overview of the rig==
Here is an overview of how the rig works: As stated before, our previous animating process was limited to FK only, which is inefficient for Oni. So instead we desperately needed an IK/FK capable rig, to which we would be able to snap a character, so we could animate him/her.

At the same time, the rig would have to be capable of the opposite thing - snapping itself to the animated character. That's because most often the way we start out with making a new animation is copying the first or last frame of the preceeding animation. This functionality has been implemented, and is called Pose Matching. The way it works is simple - it uses bone constraints in rig controller bones targeting the character model in order to snap the rig to the model.

The rig uploaded on Oni Mod Depot contains three Konokos by default: One T-Posed Konoko and two animated ones, all stored in their own collections. The T-Posed Konoko is there because it was easiest to build the rig off a T-Pose, while the remaining two ones, stored in Pose 1 and Pose 2 collections, is where you are supposed to store your animated characters, to which you can Pose Match, and thus check if Pose Matching works as intended.

Because Oni does not store its animations in form of an armature, but rather as locations and rotations of 19 objects organized in a parent-child relationship, this forces us to use the earlier mentioned object and bone constraints. This is also creates a big problem: in order to animate, rotation and location data from the 19 character body parts have to be transformed onto the rig, and then the body parts have to be constrained to the rig. Once you are done animating and you want to export your animation, you have to do the reverse: transform the animation from the rig onto the 19 body parts, and then disable the constraints. This is quite inconvenient, because all of the constraints (and there's a lot of them) in both the body parts and rig have to be turned on and off.

The general workflow of making animations using this rig is the following, assuming you want to make a single animation (i.e. you don't want to make a throw animation):

# Open up a Blender scene containing the rig.
# Delete either the model in Pose1 or Pose2.
# (OPTIONAL) Assuming you want to animate a different character, delete the T-posed model.
## Import your desired character with textures using -noanim.
# Import the animation you are using as a starting point.
## If you did point 3, apply the textures on the animated model.
# Using the RigBoneConstraintTargetSetter script available [[Blender#Rig_bone_constraint_target_setting_script|HERE]], set the targets of the rig's bone constraints to be the body parts of the animation you've imported.
# Using the Pose Matching functionality, constrain the rig to the imported animation (Set the IK-FK sliders on rig limbs to 1, as Pose Matching works only through FK controllers)
# For each frame that you want to remain in your animation, while having all the bones selected (or the ones you want), press Ctrl+A, select Apply Visual Transform to Pose and keyframe it.
# Disable bone constraints on the rig using the BoneConstraintEnabler script available [[Blender#Script_for_enabling.2Fdisabling_bone_constraints_in_the_selected_armature|HERE]].
# '''Make your animation.'''
# Once your animation is ready, use the Visual Transformer script available [[Blender#Visual_transformer_script|HERE]] to bake the rig keyframes into the character model.
# Using the ObjectConstraintEnabler script available [[Blender#Script_for_enabling.2Fdisabling_constraints_in_selected_objects|HERE]], disable the object constraints on the character model. '''The character model should now be animated and have the needed rotations and locations.
# Export the animation as a DAE.

==Importing animations and preparing the Blender scene==
'''The actual tutorial starts here.'''

For detailed explanation of the required OniSplit commands, please refer to the '''Oni-Blender Tutorial by EdT''' listed in the '''Tools and relevant tutorials'''.

[[Image:ARB SceneUponImportingKonokos.png|400px|right|thumb|Expected result by the end of this header]]

# Using OniSplit, export any character you want as a DAE (-extract:dae) using -noanim (T-Pose) and -blender arguments.
## As per EdT's '''Oni-Blender Tutorial''', you should get <tt>AnimationDaeWriter: custom axis conversion</tt> in OniSplit output if you've used the -blender argument. If you didn't get that on the output, it means something most likely went wrong and you won't be able to import the model into Blender (or you will be able to import it but it will be wrong).
## Assuming you wanted a textured model and thus you've exported an ONCC, you should now get a '''DAE file''' and an '''''images''''' folder containing the textures for it.
# Using OniSplit, export any two animations as an XML (-extract:xml) using -anim-body (lets you specify the character you want) and -blender arguments.
## You should get '''one DAE and an XML file for each animation, totalling four files.'''
# Open up Blender and set your scene's frame rate to 60 FPS. If you don't, the keyframes of the imported animations will get tightened up together, because Blender's default scene framerate is 24 FPS.
# Import the -noanim model into Blender first ('''MAKE SURE YOU CHECK THE ''Import Unit'' BOX''', otherwise you will import the model with arbitrary units which will break everything and will be basically unadjustable later)
# Import the animations into Blender ('''ALSO MAKE SURE YOU CHECK THE ''Import Unit'' BOX EACH TIME''')
# At this point the -noanim/T-posed model in the scene should have no suffix in its body part names, while the animated models should have ''.001'' and ''.002'' suffixes. This is intended; the T-posed model will serve for building the metarig and editing the rig once it's generated, while the animated models are needed for pose matching purposes, where the suffixes are useful for setting up the bone constraints.
# Create three new collections in the Outliner, name them ''T-pose'', ''Pose 1'' and ''Pose 2''. These three collections allow you to quickly hide the respective models from the Viewport using the eye icon in the Outliner.
## Move the T-Posed model to ''T-pose'', and move ''.001'' and ''.002'' animated models to ''Pose 1'' and ''Pose 2'' collections respectively.
# If you've imported the textured model, [[#Broken_alpha_transparency_and_textures_on_animated_models|apply textures to the animated models and fix the alpha transparency issue.]]
# At this point, your scene should look as shown in the screenshot on the right.
# You can hide the Pose 1 and Pose 2 collections - they won't be changed in this tutorial anymore.

==Adjusting T-posed model's Z location==
At this moment the T-posed model is sunk to the ground. That's because the pelvis location is set to 0,0,0. All of the animations in Oni have their heights adjusted [[XML:TRAM#List_of_tags.2C_types.2C_and_flags|(through the <Height> tags)]] so that the pelvis is roughly at Z ~ 0.9, so that the characters appear standing on the floor instead of, again, sinking into it. For this reason, we want to adjust the position of the pelvis so that the feet soles are aligned with the floor.

[[Image:PelvisZLocation.png|400px|right|thumb|Expected result by the end of this header]]

# <li value="10">Adjust the Z position of the T-posed model's Pelvis in one of the two ways:</li>
## Simply switch to Front Ortographic view (Num 1) and move the Pelvis along the Z axis so that the feet soles are roughly aligned with the floor. This will work, but if you want 100% accuracy, use the method below.
## The 3D Cursor snapping method:
### Select one of the feet in Object mode.
### Switch to Edit mode.
### Select one of the lowest-reaching vertices on the foot and Snap Cursor to Active. (Shift + S, 3)
### Switch back to object mode.
### Select the Pelvis.
### Snap Selection to Cursor. (Shift+S, 8)
### Set the X and Y locations of the pelvis to 0.
### Invert the Z location of the pelvis.
### The pelvis should be now at Z ~ 0.9 with feet soles perfectly aligned with the floor.
# At this point, your scene should look as shown in the screenshot on the right.

==Creating the Rigify metarig and adding limb flexion==
This part describes how to create a Rigify metarig and how to adjust it so that it matches the T-posed model body parts.

# <li value="12">Before you proceed to create the rig, you need to add small rotations to the limbs, which will allow Rigify to know in which direction the elbows and knees are going to bend. Otherwise, the rig will not function properly.</li>
## Add the following Z rotations to the respective body parts in accordance with the list below:

{| class="wikitable"
|-
! Z rotation !! Bones
|-
| -5 || <ul><li>right_thigh <li>left_thigh <li></ul>
|-
| -10 || <ul><li>right_calf <li>left_calf <li>right_wrist <li>left_wrist </ul>
|-
| 5 || <ul><li>right_biceps <li>left_biceps <li> right_handfist <li>left_handfist <li>right_foot <li>left_foot</ul>
|}

# <li value="13">Enable Rigify in Blender if you haven't already - you can do that by going to Edit / Preferences / Addons and looking it up, as Rigify comes with by Blender by default.</li>
# Add a Basic Human Metarig to the scene. ( Add Menu / Armature / Basic / Basic Human (Meta-Rig) )
## Scale the rig by 10 or so that it's roughly the size of the character.
## Apply the scale. ( Object / Apply / Scale )
# Go to Metarig's Object Data Properties tab and:
## Open Viewport Display,
## Check ''In Front'' box to make the metarig easier to select when your Viewport is in Solid or Material Preview shading modes,
## Check the ''Axes'' box to see the local axes of each bones - this makes their rolls easier to understand.
# Remove the following bones from the Metarig:
*pelvis.L
*pelvis.R
*breast.L
*breast.R
*spine.005
*spine.006
# <li value="17">Go to Edit mode, select Bone Properties tab and change the ''Connected'' box of the following Metarig's bones accordingly to the below table:</li>

{| class="wikitable"
|-
! Bone || Connected
|-
| spine.003 || Disable
|-
| spine.004 || Enable
|-
| shoulder.l || Enable
|-
| shoulder.r || Enable
|}

# <li value="18">The default Rigify bone layer order is highly unergonomic. For this reason, reassign the following bones to bone layers in accordance with the table below. You can reassign bones' bone layers by selecting them and pressing M. Make sure you have enabled User Tooltips in Preferences / Interface - that way when you move your cursor over the layer box, a tooltip will display the layer number.</li>

{| class="wikitable"
|-
! Bones !! Bone layer
|-
| <ul><li>spine <li>spine.001 <li>spine.002 <li>spine.003 <li>spine.004 <li>shoulder.l <li>shoulder.r </ul> || 8
|-
| <ul><li>upper_arm.L <li>forearm.L <li>hand.L </ul> || 0
|-
| <ul><li>upper_arm.R <li>forearm.R <li>hand.R </ul> || 16
|-
| <ul><li>thigh.L <li>shin.L <li>foot.L <li>toe.L <li>heel.02.L </ul> || 4
|-
| <ul><li>thigh.R <li>shin.R <li>foot.R <li>toe.R <li>heel.02.R </ul> || 20
|}

# <li value="19">Go to Pose mode, select Bone Properties tab and open the Rigify Type box.</li>
# Set ''Limb Segments'' and ''B-Bone Segments'' to 1 on the bones listed below. Because Oni uses rigid body parts, Limb Segments and Bendy bones are not needed.
* upper_arm.L
* upper_arm.R
* thigh.L
* thigh.R

# <li value="20"> Disable ''Assign Tweak Layers'' checkbox on the bones listed below.</li>
* upper_arm.L
* upper_arm.R
* thigh.L
* thigh.R
* spine

# <li value="21"> Remove ''rig type'' on the ''spine.004'' bone.</li>
# Set ''rig type'' on ''spine.003'' bone to ''spines.super_head''.
# Enable the ''Connect chain'' checkbox on the ''spine.003'' bone.
# Disable the ''Widget'' checkbox on ''shoulder.L'' and ''shoulder.R bones''.
# Set ''pivot_position'' on the ''spine'' bone to 1.
# Enable the ''Custom Pivot Control'' checkbox on the ''spine'' bone.
# Assign Tweak Layer of spine.003 to 9.
# Assign FK layers for the following bones in accordance with the table below:

{| class="wikitable"
|-
! Bones !! Bone layer
|-
| <ul><li>spine <li>spine.003</ul> || 9
|-
| upper_arm.L || 1
|-
| upper_arm.R || 17
|-
| thigh.L </ul> || 5
|-
| thigh.R </ul> || 21
|}

# <li value="29">Now you need to adjust metarig's bones so that they match up with character body parts. In order to reduce the amount of needed work, switch to Edit Mode and check the X-Axis Mirror either in Options or the Tool tab.</li>
# Switch to Object mode and using the Snapping Cursor to Active, and Snapping Selection to Cursor in the Snap menu (Shift + S), keep snapping cursor to model's body parts, selecting the Metarig, switching to Edit mode, selecting the appropriate bone and snapping it to 3D Cursor. '''I believe it is intuitive which bones should be snapped to which body parts, therefore there is no need for a table describing that, with the exception of hints on what should be done about spine.004, hand.L, hand.R, toe.L, toe.R, heel.02.L and heel.02.R.'''
## There is actually nothing you need to do about the heel bones, leave them as they are.
## Snap the tails of spine.004, hand.L and hand.R to their heads and move them along the axis they're pointing at, to some whatever point that makes sense to you, e.g. furthest reaching vertex on the hand. No need to be precise here, and thus snapping - just move the tail so that it is roughly where you want it to be.
## In order to keep the toe bones aligned and properly positioned, do the following for each toe bone:
### Select the foot in object mode,
### Snap cursor to the furthest and lowest reaching vertex on the foot,
### Copy the X location of that vertex,
### Snap the bone to cursor,
### Paste the X location to the bone's head,
### Snap bone's tail to the head,
### Move the head along the Y axis by some amount will make it easy to select but not too big.
# In edit mode, set the following rolls for the Metarig bones as described below (if you don't, body parts, mainly shoulders, will get badly rotated after constraining them to the rig after its generation):
## shoulder.L, 90 degrees,
## shoulder.R, -90 degrees,
## ''All'' other bones, 0 degrees.
# Now we have to set up how our Rigify rig layers will be named and set up. Go to the Object Data Properties tab, open up Rigify Layer Names, and set the table according to the screenshot below, marked as Point 32.
# The metarig is now correctly adjusted. Your scene should look as shown in the screenshot below, marked as Point 33.
# We highly recommend to save your project here and to continue your work in a new file (i.e. save, then save as a new file and continue your work on the new file), so that you can revert to the version you had until now and adjust the Metarig if needed. You can skip this, work on a single file, adjust the metarig, delete your current rig and generate a new one, but it may or may not be less convenient to rename.
# Generate the rig. Congratulations, you have generated the rig and can move to constraining the character to it. Your scene should look as shown in the screenshot below, marked as Point 35.

{| class="wikitable"
|-
| [[Image:RigifyLayerNames.png|300px|frameless]] || [[Image:Metarig.png|400px|frameless]] || [[Image:Rig.png|400px|frameless]]
|-
! Point 32, Rigify layer names for the rig !! Point 33, fully adjusted Metarig. !! Point 35, generated rig.
|}

==Constraining the character to the rig and adding the Axis Correction Empties==
Now we get to constrain the character to the rig and later edit the rig. Unfortunately, there's even more work in editing the rig than with the metarig.
# <li value="36">Hide the metarig, it won't be needed anymore.</li>
# On the Pelvis of the T-posed character, add two Copy Rotation object constraints with the settings according to the table below. "x" means there's nothing set.
{| class="wikitable"
|-
! Setting !! Copy Rotation !! Copy Rotation.001
|-
| Target || rig || x
|-
| Order || ZYX Euler || Default
|-
| Mix || Replace || After Original
|}

# <li value="37">Copy the constraints to all of the remaining body parts.</li>
# At this point, the character is folded into Oni's default pose, described [[Importing_character_models#Oni.27s_default_orientation|HERE.]] This is hard to work with, so disable all of the object constraints with the ObjectConstraintEnabler script available [[Blender#Script_for_enabling.2Fdisabling_constraints_in_selected_objects|HERE]]. We will also fix the folded pose in a moment.
# Add a ''Copy Location'' constraint to the ''Pelvis'' and:
## Set the ''Target to ''rig'',
## Set the ''Bone to ORG-spine''.

# <li value="40">Now we need to fix the folded pose. This is done through a set of Empties with specified rotations, which are added to the rotation of each body part through the ''Copy Rotation.001'' constraint (this is also why the Mix of that constraint was set to ''After Original'').</li>
## Create a new collection in the Outliner called "''Axis Correction Empties''".
## Add six Arrows Empties, all with their Name showing in the Viewport Display. ( Object Properties / Viewport Display / Name )
## Name the empties and place them in the proposed arbitrary postions using cursor snapping, and set their rotations according to the table below - you can place them however you want, as their location does not influence the rig in any way, however, proper placement makes them easy to edit if needed. It's also proposed to place the empties one meter either in front or behind the given body part.

[[Image:AxisCorrectionEmptyPlacement.png|200px|right|thumb|Proposed Axis Correction Empties' placement]]

{| class="wikitable"
|-
! Empty !! Body Part !! In front of or behind? || X rotation || Y rotation || Z rotation
|-
| ACFeet || Either foot || Behind || -90 || -52.5 || 90
|-
| ACHandL || left_handfist || Behind || 180 || 0 || 90
|-
| ACHandR || right_handfist || Behind || 0 || 0 || 90
|-
| ACLimbs || neck || Behind || -90 || 0 || 90
|-
| ACPelvis || pelvis || Front || 90 || 8.6 || 90
|-
| ACSpine || mid || Front || 90 || 0 || 90
|}

::#<li value="4"> In your Viewport, open the Viewport Overlay and enable Relationship Lines. These are the lines that will show you lines from constrained objects to their targets. They will give you a better sense of how body parts are copying rotations from the Empties you are about to make. You can also turn Relationship Lines off at any point if they're making the scene hard to read.</li>
::# Set the ''Bones'' of ''Copy Rotation'' and ''Targets'' of ''Copy Rotation.001'' constraints in character's body parts in accordance with the table below. The table may be intimidating, but it should be logical enough and easy to copy and paste the targets and bones - all of the body parts get targeted to a corresponding ORG bone in the rig through ''Copy Rotation'' and get their Axis Correction rotation added through ''Copy Rotation.001'' set to appropriate empty.

[[Image:RigCharacterConstrained.png|600px|right|thumb|Expected result by the end of this header]]

{| class="wikitable"
|-
! Body part !! Copy Rotation / Bone !! Copy Rotation.001 / Target
|-
| pelvis || ORG-spine || ACPelvis
|-
| mid || ORG-spine.001 || ACSpine
|-
| chest || ORG-spine.002 || ACSpine
|-
| neck || ORG-spine.003 || ACSpine
|-
| head || ORG-spine.004 || ACSpine
|-
| right_shoulder || ORG-shoulder.R || ACLimbs
|-
| right_biceps || ORG-upper_arm.R || ACLimbs
|-
| right_wrist || ORG-forearm.R || ACLimbs
|-
| right_handfist || ORG-hand.R || ACHandR
|-
| left_shoulder || ORG-shoulder.L || ACLimbs
|-
| left_biceps || ORG-upper_arm.L || ACLimbs
|-
| left_wrist || ORG-forearm.L || ACLimbs
|-
| left_handfist || ORG-hand.L || ACHandL
|-
| right_thigh || ORG-thigh.R || ACLimbs
|-
| right_calf || ORG-shin.R || ACLimbs
|-
| right_foot || ORG-foot.R || ACFeet
|-
| left_thigh || ORG-thigh.L || ACLimbs
|-
| left_calf || ORG-shin.L || ACLimbs
|-
| left_foot || ORG-foot.L || ACFeet
|}

#<li value="41">Enable the object constraints in the character body parts using the ObjectConstraintEnabler script.</li>
# At this point, you should be able to pose the character, as shown in the screenshot on the right.

==Removing and editing the rig bones==
There are still things to do; if you play around posing your character, you will find out the spine behaviour to be somewhat lackluster, and lacking control over the mid and chest bones. This will now be addressed, and later, bone constraints need to be added to rig controller bones. Let's start off with deleting all the controller bones we don't need.

#<li value="43">Select the rig, go to Object Data Properties, Viewport Display and enable In Front. The rig will now always render in front of the character, making it easier to select.</li>
# In Edit mode, go to Object Data Properties tab / Skeleton, select Layer 29 (the DEF/Deform) and delete all bones in it.
# Select layer 28, and move the root bone to layer 24 (Change Bone Layer, default shortcut is M)
# Remove the bones listed below from the rig. Keep in mind it's possible to enable just one layer at a time for your convenience. For the record, we will not be editing MCH or ORG layers until later, so you can ignore their layers for now. '''IMPORTANT NOTE: Be sure to not delete tweak_spine.001 accidentally, as it's necessary for the rig to function properly.'''

{| class="wikitable"
|-
! Bone !! Layer
|-
| tweak_spine || Torso
|-
| tweak_spine.002 || Torso
|-
| tweak_spine.003 || Torso (Tweak)
|-
| spine_fk.001 || Torso (Tweak)
|-
| spine_fk.002 || Torso (Tweak)
|-
| upper_arm_tweak.L || Arm.L (IK)
|-
| forearm_tweak.L || Arm.L (IK)
|-
| hand_tweak.L || Arm.L (IK)
|-
| upper_arm_tweak.R || Arm.R (IK)
|-
| forearm_tweak.R || Arm.R (IK)
|-
| hand_tweak.R || Arm.R (IK)
|-
| thigh_tweak.L || Leg.L (IK)
|-
| shin_tweak.L || Leg.L (IK)
|-
| foot_tweak.L || Leg.L (IK)
|-
| thigh_tweak.R || Leg.R (IK)
|-
| shin_tweak.R || Leg.R (IK)
|-
| foot_tweak.R || Leg.R (IK)
|}

#<li value="47">Using 3D Cursor snapping, snap ''torso'' and ''torso_pivot'' bones to the ''mid'' body part.</li>
##Since ''torso'' and ''torso_pivot'' are of the same size, etc. and thus are overlapping each other, feel free to move their tails a bit in the appropriate axis. This applies to all overlapping bones in the rig - if they overlap, move the tail in the axis parallel to the bone.
#Reparent ''shoulder.L'' and ''shoulder.R'' bones from ''ORG-spine.003'' to ''ORG-spine.002''.
# Controller bones are now adjusted, and we can move on to ORG and MCH layers. Select the ORG layer (31), reparent the bones and set their ''Connected'' box according to the table below. '''x''' means no change is needed.

{| class="wikitable"
|-
! Bone !! Parent !! Connected
|-
| ORG-spine || root || x
|-
| ORG-spine.001 || ORG-spine || Yes
|-
| ORG-spine.002 || ORG-spine.001 || Yes
|-
| ORG-shoulder.L || ORG-spine.002 || x
|-
| ORG-shoulder.R || ORG-spine.002 || x
|-
| ORG-upper_arm.L || x || No
|-
| ORG-upper_arm.R || x || No
|}

#<li value="50">Select the MCH layer (3) and remove the following bones:</li>
#*MCH-thigh_tweak.L
#*MCH-thigh_tweak.R
#*MCH-shin_tweak.L
#*MCH-shin_tweak.R
#*MCH-foot_tweak.L
#*MCH-foot_tweak.R
# Snap ''MCH-torso.parent'' and ''MCH-torso_pivot'' to the ''mid'' body part. (You can also snap them to ''MCH-spine'' or ''MCH-spine.001'' bones as they're snapped to ''mid'' as well)
# With X-Axis mirror enabled, select the MCH-forearm_ik.R bone and extrude it perpendicularly to the axis of the arm. You should now have the MCH-forearm_ik.R.001 and MCH-forearm_ik.L.001 bones. These bones are needed for the wrist snapping function which we'll implement later.

==Editing the bone constrants of ORG and MCH bone layers==
Now's the time to edit and add bone constraints.

#<li value="53">Switch to Pose mode and add a ''Copy Rotation'' bone constraint to MCH-forearm_ik.R.001 and MCH-forearm_ik.L.001 bones that you've added in previous points, targeting MCH-forearm_ik.R and MCH-forearm_ik.L bones (i.e. for the ''MCH-forearm_ik.R.001'', ''Target'' is ''rig'', while ''Bone'' should be set to ''MCH-forearm_ik.R.001'')</li>
# Select the ORG layer.
# Add bone constraints in accordance to the table below.

{| class="wikitable"
|-
! Bone !! Bone Constraint !! Target !! Target/Bone
|-
| ORG-spine || Copy Transforms || rig || MCH-WGT-hips
|-
| ORG-spine.001 || Copy Rotation || rig || tweak_spine.001
|-
| ORG-spine.002 || Copy Transforms || rig || MCH-WGT-chest
|}
#<li value="55">Delete the ''Stretch to'' bone constraint from ''ORG-spine.003''.</li>
#Set the ''Bone'' in the ''Copy Transforms'' bone constraint in ''ORG-spine.003'' to ''neck''.
#Select the MCH layer.
# Select the MCH-pivot bone.
## Set the Influence of the Copy Transforms bone constraint to 1.
## Add a Copy Rotation bone constraint, set it to rig / ORG-spine.002 and set its influence to 0.5.
# Select the MCH-spine.001 bone, and set the Influence of the Copy Transforms bone constraint to 0.
# Select the MCH-spine.002 bone.
## Set the Influence of the Copy Transforms bone constraint to 1.
## Add a Copy Location bone constraint, and set it to rig / ORG-spine.002.
# Select the MCH-STR-neck bone.
## Set the Rotation of the Stretch To bone constraint from Swing to XZ.
## Add a Damped Track bone constraint.
### Move it to the top of the bone constraint list.
### Set it to rig / head.
### Set the Track Axis to Y if it isn't already.
# For both MCH-upper_arm_ik_stretch.L and MCH-upper_arm_ik_stretch.R bones, do the following:
## Set the Rotation of the Stretch To bone constraint from Swing to XZ.
## Add a Damped Track bone constraint.
### Move it to the top of the bone constraint list.
### Set it to rig / hand_ik (.L or .R appropriately if it's a right or left hand).
### Set the Track Axis to Y if it isn't already.
# For both MCH-thigh_ik_stretch.L and MCH-thigh_ik_stretch.R bones, do the following:
## Set the Rotation of the Stretch To bone constraint from Swing to XZ.
## Add a Damped Track bone constraint.
### Move it to the top of the bone constraint list.
### Set it to rig / MCH-foot_roll (.L or .R appropriately if it's a right or left leg).
### Set the Track Axis to Y if it isn't already.
# Disable the ''Stretch'' checkbox in both of the IK bone constraints in the following bones:
#*MCH-forearm_ik.L
#*MCH-forearm_ik.R
#*MCH-shin_ik.L
#*MCH-shin_ik.R

==Changing custom shapes of rig controller bones==
We're getting close to the end. There's still a bit of work to do, but all that remains relates to the rig controller bones in Pose mode.
This short header will focus on changing the shapes of the controller bones - these changes are purely visual and have no functional effect on the rig, however, they do make it more more ergonomic and easier to read.
[[Image:Rig After Editing Custom Shapes.png|200px|right|thumb|Rig's expected state at point 69]]
#<li value="65>Switch over to all other bone layers except the MCH and ORG layers - all that was related to them is now done.</li>
#Select the tweak_spine.001 bone:
## Set the Custom Object to WGT-rig_thigh_parent.L - this will make it much more easier to read.
## Set the Scale to 1.5.
## Disable the ''Scale to Bone Length'' checkbox.
# Select the spine_fk bone:
## Disable the ''Scale to Bone Length'' checkbox.
## Set the Scale to 0.
#For both hand_ik.R and hand_ik.L bones, disable the ''Scale to Bone Length'' checkbox.
#For both foot_ik.R and foot_ik.L bones, do the following:
## Disable the ''Scale to Bone Length'' checkbox.
## Set the Scale to 2.
#For both toe.R and toe.L, set the scale to 0. At this point, the rig should look as shown in the screenshot on the right.

==Editing the rig_ui.py script==
Now we'll need to edit the Rig Layers panel a bit and add the wrist snapping functionality by putting three code snippets into rig_ui.py and running it.

#<li value="71"> Go to the Scripting tab and select the rig_ui.py script.
#Right at the start of the script you will see the <code>rig_id</code> field. Copy its value and save it in some text editor, as you'll be pasting it in the next few steps.
#Find the following line (use another text editor if you can't find it in Blender's Text Editor):

<pre> props.bones = '["upper_arm_ik.L", "upper_arm_ik_target.L", "hand_ik.L"]'</pre>

Add the following code snippet below it - this will add a button and functionality for the wrist snapping on the '''left''' arm - using the MCH-forearm_ik.L.001 bone that was created in points 52 and 53.
Also, replace <code>'''YOURRIGID'''</code> with your <code>rig_id</code> from point 71.

<pre>
group2 = group1.row(align=True)
props = group2.operator('pose.rigify_generic_snap_YOURRIGID', text='IK wrist (hand.L)', icon='SNAP_ON')
props.output_bones = '["hand_ik.L"]'
props.input_bones = '["MCH-forearm_ik.L.001"]'
props.ctrl_bones = '["MCH-forearm_ik.L.001"]'
props.tooltip = 'IK hand to wrist'
</pre>

#<li value="74"> Find the following line:
<pre> props.bones = '["upper_arm_ik.R", "hand_ik.R", "upper_arm_ik_target.R"]' </pre>
Add the following code snippet below it - this will add a button and functionality for the wrist snapping on the '''right''' arm. Also, replace <code>'''YOURRIGID'''</code> with your <code>rig_id</code> from point 71.

<pre>
group2 = group1.row(align=True)
props = group2.operator('pose.rigify_generic_snap_YOURRIGID', text='IK wrist (hand.R)', icon='SNAP_ON')
props.output_bones = '["hand_ik.R"]'
props.input_bones = '["MCH-forearm_ik.R.001"]'
props.ctrl_bones = '["MCH-forearm_ik.R.001"]'
props.tooltip = 'IK hand to wrist'
if is_selected({'upper_arm_ik.R', 'hand_ik.R', 'upper_arm_parent.R', 'upper_arm_ik_target.R'}):
</pre>

#<li value="75"> Find the following line:

<pre> row.prop(context.active_object.data, 'layers', index=8, toggle=True, text='Torso') </pre>

Change it to the following:

<pre>
row.prop(context.active_object.data, 'layers', index=9, toggle=True, text='Pose Matching')

row = col.row()
row.separator()
</pre>

#<li value="76"> Find the following line:
<pre> row.prop(context.active_object.data, 'layers', index=9, toggle=True, text='Torso (Tweak)')</pre>

Change it to the following:
<pre> row.prop(context.active_object.data, 'layers', index=8, toggle=True, text='Torso')</pre>

[[Image:IKWrist.png|200px|right|thumb|Rig's expected state at point 80.]]
[[Image:ModifiedRigLayers.png|200px|right|thumb|Rig's expected state at point 80, with hand_ik.R selected, showing the newly added IK wrist snapping functionality.]]

#<li value="77">Find the following code:</li>
<pre>
row.prop(context.active_object.data, 'layers', index=21, toggle=True, text='Leg.R (FK)')

row = col.row()
row.separator()
</pre>

Remove the <code>row = col.row()</code> and <code>row.seperator()</code> lines.

#<li value="78"> Find the following line:

<pre> row.prop(context.active_object.data, 'layers', index=28, toggle=True, text='Root')</pre>

Change the value of <code>index</code> to 24. Index is the layer number, and Root should be layer 24, not 28.

#<li value="79">We recommend backing up your file at this point.
#Run the script, and move to the Layout tab. Your rig should look as shown in the screenshots on the right.

==Adding the Rigify Axis Correction Empties==
Before we add the Pose Matching functionality, we need to create Axis Correction Empties that will account for Rigify's axis orientation.
#<li value="81">Switch to Object Mode.
#Duplicate the ''Axis Correction Empties'' collection and rename it to ''Rigify Axis Correction Empties''
## Rename the ACPelvis.001 to RACHead and move it in the global Z axis so that it is aligned with the head along the Y axis (or 3D cursor snap it)
## Rename the remaining empties in the newly-made collection by removing the ''.001'' suffix and changing the ''AC'' prefix to ''RAC''.
## Set the rotations of the empties according to the table below:

{| class="wikitable"
|-
! Empty !! X rotation || Y rotation || Z rotation
|-
| RACFeet || 38.1 || 90 || 0
|-
| RACHandL || -180 || 0 || 90
|-
| RACHandR || 0 || 0 || -90
|-
| RACHead || -90 || -90 || 0
|-
| RACLimbs || 90 || 90 || 0
|-
| RACSpine || 180 || -90 || 0
|}

==Adding bone constraints to rig controller bones and drivers==
This is the final section of this tutorial. Now we just have to add the Pose Matching functionality, so we can constrain the rig to imported animations in Pose 1 and Pose 2 collections. We do that by adding two new bones to the rig, bone constraints to the rig controller bones and then drivers which will control the influence of the bone constraints through the Z location of the newly added bones. We will also

#<li value="83">Select the rig, go to Edit mode and select the Pose Matching layer.
#Add a new bone named ''Pose1''.
#Set its transforms as listed below (or make it as big as you want, this is purely a visual/ergonomic matter):
#*Head X,Y,Z: 1,0,0
#*Tail X,Y,Z: 1,0,1
#Duplicate the bone and rename it to ''Pose2''.
#Set its transforms as listed below (it will be simply mirrored along the X axis)
#*Head X,Y,Z: -1,0,0
#*Tail X,Y,Z: -1,0,1
#Switch to Pose mode.
#For both Pose1 and Pose2 bones, select them, go to Bone Properties tab, Viewport Display, Custom Shape and set the Custom Object to WGT-rig_shoulder.L.
##You can also set the Scale to 10 and disable the ''Scale to Bone Length'' checkbox for them if you want.
#For now, move both Pose 1 and Pose 2 in Global Z axis so that they are below the "floor" (XY plane).
#Select the Torso layer and all of the FK layers in the Rig Layers panel.
#Select the ''hips'' bone.
##Add ''three'' Copy Rotation bone constraints, and move the one without the suffix to the bottom of the list (so the order of the bone constraints going from the top to bottom is ''Copy Rotation.001'', ''Copy Rotation.002'', ''Copy Rotation''). ''Copy Rotation.001'' and ''Copy Rotation.002'' will be used for pose matching, ''Copy Rotation'' will be used for axis correction.
##In the ''Copy Rotation'' constraint, set the ''Mix'' to ''After Original''.
#Now we'll have to add the drivers controlling the influence of each Copy Rotation constraint. As shown in Pierrick Picaut's tutorial, you can do that by right clicking on the Influence value and pressing ''Add Driver'' (same applies to any other property in any other constraint). Once you add a driver, you can edit it either through ''Edit Driver'' or through the Driver Editor - both are selectable within the same menu.
##Add a driver to the ''Influence'' of each ''Copy Rotation'' constraint in accordance with the table below:
{| class="wikitable"
|-
! Copy Rotation.001 !! Copy Rotation.002 !! Copy Rotation
|-
|
*Driver Type: ''Scripted Expression'' (default setting)
*Expression: ''var''
*Amount of input variables: one (default setting)
*Input Variable type: ''Transform Channel'' (default setting)
*Input Variable name: ''var'' (default setting)
*Object: ''rig''
*Bone: ''Pose1''
*Type: ''Z Location''
*Space: ''World Space'' (default setting)
||
Same settings as in Copy Rotation.001, with the exception of:
*Bone: ''Pose2''
||
*Driver Type: ''Scripted Expression'' (default setting)
*Expression: ''max(var1,var2)'' (press Enter to get rid of the invalid expression error, if you have it)
*Amount of input variables: two ('''press ''Add Input Variable''''')

First input variable:
*Input Variable type: ''Transform Channel'' (default setting)
*Input Variable name: ''var1''
*Object: ''rig''
*Bone: ''Pose1''
*Type: ''Z Location''
*Space: ''World Space'' (default setting)

Second input variable:
*Input Variable type: ''Transform Channel'' ('''be sure to change it to this''', added variables have ''Single Property'' set as default)
*Input Variable name: ''var2''
*Object: ''rig''
*Bone: ''Pose2''
*Type: ''Z Location''
*Space: ''World Space'' (default setting)

|}

#<li value="94">You can check if the drivers are working by moving Pose1 and Pose2 bones along global Z axis and checking if the Influence of Copy Rotation bone constraints in ''hips'' or Input Variable values in their drivers change.
#Copy the bone constraints from the ''hips'' bone to the following bones:
#*tweak_spine.001
#*chest
#*shoulder.R
#*shoulder.L
#*neck
#*head
#*upper_arm_fk.R
#*upper_arm_fk.L
#*forearm_fk.R
#*forearm_fk.L
#*hand_fk.R
#*hand_fk.L
#*thigh_fk.R
#*thigh_fk.L
#*shin_fk.R
#*shin_fk.L
#*foot_fk.L
#*foot_fk.R
#Unfortunately, because Blender at this moment does not copy drivers when copying bone constraints, the bone constraints you've just copied are lacking the drivers. Because of this, you have to copy the drivers manually - simply right click on the ''Influence'' value of ''Copy Rotation'' constraint, press ''Copy Driver'', and go through all bones in the upper list and ''Paste Driver'' onto the Influence of the ''Copy Rotation'' in each bone. '''Do this for all three ''Copy Rotation'' bone constraints.'''
#Add two ''Copy Location'' constraints to ''torso'' and ''torso_pivot'' bones, and make sure they're named ''Copy Location.001'' and ''Copy Location.002''.
#Copy Influence Drivers from any of the bones in point 96 and paste them into the ''Influence'' of ''Copy Location'' constraints in ''torso'' and ''torso_pivot'', in accordance with the numbers of bone constraints (e.g. copy the driver from ''hips''' ''Copy Rotation.001'' Influence and paste it into Influence of ''Copy Location.001'' in ''torso'' and ''torso_pivot'').
#Set the ''Copy Rotation'' constraints' Axis correction ''Target'' in accordance with the table below.

{| class="wikitable"
|-
! Bone !! Copy Rotation target
|-
| hips || RACSpine
|-
| tweak_spine.001 || RACHead
|-
| chest || RACSpine
|-
| neck || RACHead
|-
| head || RACHead
|-
| shoulder.R || RACLimbs
|-
| shoulder.L || RACLimbs
|-
| upper_arm_fk.R || RACLimbs
|-
| upper_arm_fk.L || RACLimbs
|-
| forearm_fk.R || RACLimbs
|-
| forearm_fk.L || RACLimbs
|-
| hand_fk.R || RACHandL
|-
| hand_fk.L || RACHandR
|-
| thigh_fk.R || RACLimbs
|-
| thigh_fk.L || RACLimbs
|-
| shin_fk.R || RACLimbs
|-
| shin_fk.L || RACLimbs
|-
| foot_fk.R || RACFeet
|-
| foot_fk.L || RACFeet
|}

[[Image:RigFinished.png|200px|right|thumb|Finished rig showing the pose matching functionality]]

#<li value="100"> Select any FK (green) bone and set the IK-FK slider to 1. Do this for all four limbs. This has to be done because pose matching works only through FK.
# Using the [[Blender#Rig_bone_constraint_target_setting_script|RigBoneConstraintTargetSetter script]], set the targets for the ''Copy Rotation.001'' and ''Copy Rotation.002'' bone constraints. You can do that by having the rig in Pose mode, going to the Scripting tab, copying and pasting the script, and running it with <code>prefix</code> value set to 1, and then set to 2.
# If you didn't get any errors, move one of the Pose bones in the global Z axis above the XY plane - the T-posed character should now snap to one of the animations in the ''Pose'' collections, as shown in the screenshot on the right.
# Congratulations! The rig is now ready to be used.

[[Category:Modding tutorials]]

Using the Rigify animation rig

2022-05-20T11:35:05Z

Delano762: Added some basic info to General workflow of animating for Oni using Rigify

==Introduction==
This article is intended to explain the workflow of using the [http://mods.oni2.net/node/388 Rigify-based animation rig for Blender] (made by geyser) for the purpose of making Oni animations, and also how to use it, and what are the Oni-specific additions to it that we've made.

==Prerequisite tutorials==
As this rig is now intented to be used together with BlenderOni, it is necessary to be familiar with either:
* [[BlenderOni|BlenderOni's documentation,]]
* [https://www.youtube.com/watch?v=pA_Y8QBCvPI BlenderOni's explanatory video,] particularly time ranges from 0:00 - 3:07 and 21:24 - 48:05 (that's part 1 and 3 of the video).

Besides that, I highly recommend watching the tutorials below if you feel you're lacking knowledge in any of these subjects:

General Blender basics:

* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins]

Practical and intuitive explanation of what Inverse and Forward Kinematics (IK/FK) are - this is explained in Maya, but same principles apply in every 3D editing program including Blender:
* [https://www.youtube.com/watch?v=p6PYKyxR0aY Animating with IK and FK]

Basics of using Rigify - '''all you need to know about animating with Rigify is stored in the video below.''' There is no point in making a tutorial on how to use the rig controllers themselves here - it's all in the video below:

* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify Tutorial #08 - Posing the Rigify rig] by CGDive

(OPTIONAL) Tutorial on how to create the rig described here - this is strictly optional; the only practical reason to make your own rig is for the purpose of adjusting its controllers to a specific character, however, the advantage that you get out of that is purely visual and a marginal one at that - if you've built your rig for Konoko, there's nothing stopping you from using it on a TCTF SWAT - the limb controllers will be only slightly out of place, which doesn't impact animating in any way. So ultimately you may want to go through this if you want to learn how this rig works, find this rig confusing, or even just for the bunch of great Youtube tutorials linked in that tutorial.

Also, it's worth noting that a huge part of this article is in fact copy-pasted from this tutorial.

* [[Creating_an_animation_rig_in_Blender|Creating an animation rig in Blender]]

==Required tools and commands==
There are several things worth knowing before you start using the rig, tools to get and tutorials to have ready to reference for commands.

===Tools and relevant tutorials===
* '''[[BlenderOni|BlenderOni]]''' - this Blender addon is an integral companion tool for this rig - it contains a number of scripts which automate a lot of operations required to make any use out of the rig. Without those scripts, these operations (e.g. constraining the model to the rig and vice versa) would have to be done manually, which takes a ridiculous amount of time.
[[Image:Cmder.png|200px|right|thumb|Screenshot showing Cmder's capabilities within the context of modding Oni]]
* [http://mods.oni2.net/node/38 '''Current version of OniSplit.'''] This is the tool needed to import and export assets out of Oni. '''DO NOT USE OniSplit GUI or Vago for importing Oni assets into Blender''' - neither of these weren't updated in a long time, and thus they don't support OniSplit's v0.9.99.2 -blender option. You can still use them for other purposes though, such as sounds and converting .oni files to XMLs, etc.
* [https://docs.google.com/document/d/175uJGklYASAgrFjxuUG4-kJRDoMTjjP7GvNxSj1GscU/edit '''Oni-Blender tutorial'''] by EdT. Please read this in entirety to know likely-to-happen issues and refer to this as your guide for OniSplit commands relating to Blender.
* [http://oni.bungie.org/forum/viewtopic.php?pid=23230#p23230 '''Brief overview on creating TRAMs'''] by EdT - while this was written with XSI in mind, this is still relevant as the process for preparing the XML files for Oni is still the same. Also the next post in that thread, called '''Brief walk through on modifying a TRAM,''' is an example of that overview put into practice.

===Optional tools and tutorials===
* [https://cmder.net/ '''Cmder'''] (Windows only) - because OniSplit is a command line tool, it is highly recommended to get any upgrade to Windows' Command Prompt. As shown in the screenshot on the right, Cmder allows you to start it from the context menu in any selected folder, and it also remembers your most recently used commands, vastly improving your workflow when you're forced to use any command line tools.
* [https://docs.blender.org/manual/en/2.81/addons/rigging/rigify.html '''Rigify documentation'''] - it's a plugin for Blender designed to automate a lot of rigging work. The rig described here is generated using Rigify. Take a look if you're interested and want to learn more, but you don't have to know Rigify's documentation to use this rig.

==General workflow of animating for Oni using Rigify==
The most common way to animate characters is to create an armature (also known as a rig) to which the character model is constrained, usually through vertex weights specifying how much a given vertex is controlled by the given controller on a scale from 0 to 1, with all weights summing up to 1. The rig contains a number of controller bones that allow to animate more easily. Then, the animations are usually imported into the game along with the armatures, therefore the animation is stored along with the armature. An example of a game storing animations this way is Halo: Combat Evolved.

Oni character models are divided into 19 rigid body parts organized in a parent-child relation, with the pelvis bone being the root bone, which effectively forms an FK rig. The animations are stored in TRAM files, containing rotation data for each of the 19 body parts, and also location data for the pelvis. There is no armature stored within the game files, therefore in order to use a rig on Oni characters, it is necessary to constrain each of the 19 body parts to the rig bones individually instead of mesh vertices. Also, this automatically means that Oni's way of storing animations is a destructive one - the data stored in the rig bones that are not direct functional equivalents to Oni character body parts will get lost once the animation is baked into body parts with Visual Transform.

The general workflow of making animations using this rig is the following, assuming you want to make a single animation (i.e. you don't want to make a throw animation):

# Open up a Blender scene containing the rig.
# Delete either the model in Pose1 or Pose2.
# (OPTIONAL) Assuming you want to animate a different character, delete the T-posed model.
## Import your desired character with textures using -noanim.
# Import the animation you are using as a starting point. For more detailed information on how to import an Oni animation to Blender, see the next header.
## If you did point 3, apply the textures on the animated model.
# Using the ''Set Rig Bone Constraint Targets'' option in BlenderOni, set the targets of the rig's bone constraints to be the body parts of the animation you've imported.
# Using the Pose Matching functionality, constrain the rig to the imported animation (Set the IK-FK sliders on rig limbs to 1, as Pose Matching works only through FK controllers)
# For each frame that you want to remain in your animation, while having all the bones selected (or the ones you want), either:
## Press Ctrl+A, select ''Apply Visual Transform'' to Pose and keyframe it,
## Or use the ''Bone Visual Transformer'' option in BlenderOni to bake frames within a specified frame range.
# Disable bone constraints on the rig using the ''Bone Constraint Switch'' option in BlenderOni.
# '''Make your animation.'''
# Once your animation is ready, use the ''Object Visual Transformer'' option in BlenderOni to bake the rig keyframes into the character model.
# Using the ''Object Constraint Switch'' option in BlenderOni, disable the object constraints on the character model. '''The character model should now be animated and have the needed rotations and locations.
# Export the animation as a DAE.

==Importing Oni animations to Blender==
This header describes how to import Oni animations to Blender.

For detailed explanation of the required OniSplit commands, please refer to the '''Oni-Blender Tutorial by EdT''' listed in the '''Tools and relevant tutorials'''.

# Assuming the character you want to animate isn't in your rig file, then using OniSplit, export any character you want as a DAE (-extract:dae) using -noanim and -blender arguments.
## As per EdT's '''Oni-Blender Tutorial''', you should get <tt>AnimationDaeWriter: custom axis conversion</tt> in OniSplit output if you've used the -blender argument. If you didn't get that on the output, it means something most likely went wrong and you won't be able to import the model into Blender (or you will be able to import it but it will be wrong).
## Assuming you wanted a textured model and thus you've exported an ONCC, you should now get a '''DAE file''' and an '''''images''''' folder containing the textures for it.
# Using OniSplit, export the animation you want as an XML (-extract:xml) using -anim-body (lets you specify the character you want) and -blender arguments.
## You should get '''one DAE and one XML file for the animation.'''
# Open up a Blender scene containing the rig.
# Delete either the model either in Pose1 or Pose2 collection.
# Import the animation into Blender ('''MAKE SURE YOU CHECK THE ''Import Unit'' BOX EACH TIME''', otherwise you will import the model with arbitrary units which will break everything and will be basically unadjustable later))
# Import the -noanim model into Blender ('''ALSO MAKE SURE YOU CHECK THE ''Import Unit'' BOX''')
# Move the animated model to either Pose1 or Pose2 collection.
# If you've imported the textured model, [[Blender#Lack_of_textures_on_animated_models|apply textures to the animated models and fix the alpha transparency issue]].

==Added functionalities==
This header describes functionalities added to the rig by geyser that are not normally present in Rigify.

===Pose matching===
The way we do animations is we almost universally start by copying the first or last frame of the preceeding animation. For this reason, we needed functionality that would allow us to snap the rig to an animated Oni character. The way it works, it that it uses bone constraints in rig controller bones targeting the character model in order to snap the rig to the model. The influence of the bone constraints is controlled through the Z location of Pose1 and Pose2 bones in the Pose Matching layer, which is done through drivers.

To snap the rig to the animation in one of the Pose collections, simply move the appropriate Pose bone above the XY plane while in Pose mode.

{| class="wikitable"
|-
! Pose1 and Pose2 below the XY plane !! Rig snapped to the animation in Pose 1 collection !! Rig snapped to the animation in Pose 2 collection
|-
| [[Image:Unposed.png|300px|frameless|center]] || [[Image:Pose1.png|300px|frameless|center]] || [[Image:Pose2.png|300px|frameless|center]]
|-
|}

===Wrist snapping===
Often when using the IK handles for the arms you will find out that most of the time, you will need the hand to have the same rotation as the forearm. Normally this would mean that you would have to rotate the hands all the time, because IK handles are mainly moved around, and rotated later. For this reason, the wrist snapping functionality was implemented - you can simply copy the rotation of the forearm to the hand by pressing the "IK wrist" button.
{| class="wikitable"
|-
! Both of the hands after just moving them around... !! Effects of using the IK Wrist button
|-
| [[Image:IK Wrist Example1.png|500px|frameless|center]] || [[Image:IK Wrist Example2.png|500px|frameless|center]]
|-
|}

[[Category:Modding tutorials]]

Using the Rigify animation rig

2022-05-19T16:15:36Z

Delano762: /* Required tools and commands */

==Introduction==
This article is intended to explain the workflow of using the [http://mods.oni2.net/node/388 Rigify-based animation rig for Blender] (made by geyser) for the purpose of making Oni animations, and also how to use it, and what are the Oni-specific additions to it that we've made.

==Prerequisite tutorials==
As this rig is now intented to be used together with BlenderOni, it is necessary to be familiar with either:
* [[BlenderOni|BlenderOni's documentation,]]
* [https://www.youtube.com/watch?v=pA_Y8QBCvPI BlenderOni's explanatory video,] particularly time ranges from 0:00 - 3:07 and 21:24 - 48:05 (that's part 1 and 3 of the video).

Besides that, I highly recommend watching the tutorials below if you feel you're lacking knowledge in any of these subjects:

General Blender basics:

* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins]

Practical and intuitive explanation of what Inverse and Forward Kinematics (IK/FK) are - this is explained in Maya, but same principles apply in every 3D editing program including Blender:
* [https://www.youtube.com/watch?v=p6PYKyxR0aY Animating with IK and FK]

Basics of using Rigify - '''all you need to know about animating with Rigify is stored in the video below.''' There is no point in making a tutorial on how to use the rig controllers themselves here - it's all in the video below:

* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify Tutorial #08 - Posing the Rigify rig] by CGDive

(OPTIONAL) Tutorial on how to create the rig described here - this is strictly optional; the only practical reason to make your own rig is for the purpose of adjusting its controllers to a specific character, however, the advantage that you get out of that is purely visual and a marginal one at that - if you've built your rig for Konoko, there's nothing stopping you from using it on a TCTF SWAT - the limb controllers will be only slightly out of place, which doesn't impact animating in any way. So ultimately you may want to go through this if you want to learn how this rig works, find this rig confusing, or even just for the bunch of great Youtube tutorials linked in that tutorial.

Also, it's worth noting that a huge part of this article is in fact copy-pasted from this tutorial.

* [[Creating_an_animation_rig_in_Blender|Creating an animation rig in Blender]]

==Required tools and commands==
There are several things worth knowing before you start using the rig, tools to get and tutorials to have ready to reference for commands.

===Tools and relevant tutorials===
* '''[[BlenderOni|BlenderOni]]''' - this Blender addon is an integral companion tool for this rig - it contains a number of scripts which automate a lot of operations required to make any use out of the rig. Without those scripts, these operations (e.g. constraining the model to the rig and vice versa) would have to be done manually, which takes a ridiculous amount of time.
[[Image:Cmder.png|200px|right|thumb|Screenshot showing Cmder's capabilities within the context of modding Oni]]
* [http://mods.oni2.net/node/38 '''Current version of OniSplit.'''] This is the tool needed to import and export assets out of Oni. '''DO NOT USE OniSplit GUI or Vago for importing Oni assets into Blender''' - neither of these weren't updated in a long time, and thus they don't support OniSplit's v0.9.99.2 -blender option. You can still use them for other purposes though, such as sounds and converting .oni files to XMLs, etc.
* [https://docs.google.com/document/d/175uJGklYASAgrFjxuUG4-kJRDoMTjjP7GvNxSj1GscU/edit '''Oni-Blender tutorial'''] by EdT. Please read this in entirety to know likely-to-happen issues and refer to this as your guide for OniSplit commands relating to Blender.
* [http://oni.bungie.org/forum/viewtopic.php?pid=23230#p23230 '''Brief overview on creating TRAMs'''] by EdT - while this was written with XSI in mind, this is still relevant as the process for preparing the XML files for Oni is still the same. Also the next post in that thread, called '''Brief walk through on modifying a TRAM,''' is an example of that overview put into practice.

===Optional tools and tutorials===
* [https://cmder.net/ '''Cmder'''] (Windows only) - because OniSplit is a command line tool, it is highly recommended to get any upgrade to Windows' Command Prompt. As shown in the screenshot on the right, Cmder allows you to start it from the context menu in any selected folder, and it also remembers your most recently used commands, vastly improving your workflow when you're forced to use any command line tools.
* [https://docs.blender.org/manual/en/2.81/addons/rigging/rigify.html '''Rigify documentation'''] - it's a plugin for Blender designed to automate a lot of rigging work. The rig described here is generated using Rigify. Take a look if you're interested and want to learn more, but you don't have to know Rigify's documentation to use this rig.

==General workflow of animating for Oni using Rigify==
The general workflow of making animations using this rig is the following, assuming you want to make a single animation (i.e. you don't want to make a throw animation):

# Open up a Blender scene containing the rig.
# Delete either the model in Pose1 or Pose2.
# (OPTIONAL) Assuming you want to animate a different character, delete the T-posed model.
## Import your desired character with textures using -noanim.
# Import the animation you are using as a starting point. For more detailed information on how to import an Oni animation to Blender, see the next header.
## If you did point 3, apply the textures on the animated model.
# Using the ''Set Rig Bone Constraint Targets'' option in BlenderOni, set the targets of the rig's bone constraints to be the body parts of the animation you've imported.
# Using the Pose Matching functionality, constrain the rig to the imported animation (Set the IK-FK sliders on rig limbs to 1, as Pose Matching works only through FK controllers)
# For each frame that you want to remain in your animation, while having all the bones selected (or the ones you want), either:
## Press Ctrl+A, select ''Apply Visual Transform'' to Pose and keyframe it,
## Or use the ''Bone Visual Transformer'' option in BlenderOni to bake frames within a specified frame range.
# Disable bone constraints on the rig using the ''Bone Constraint Switch'' option in BlenderOni.
# '''Make your animation.'''
# Once your animation is ready, use the ''Object Visual Transformer'' option in BlenderOni to bake the rig keyframes into the character model.
# Using the ''Object Constraint Switch'' option in BlenderOni, disable the object constraints on the character model. '''The character model should now be animated and have the needed rotations and locations.
# Export the animation as a DAE.

==Importing Oni animations to Blender==
This header describes how to import Oni animations to Blender.

For detailed explanation of the required OniSplit commands, please refer to the '''Oni-Blender Tutorial by EdT''' listed in the '''Tools and relevant tutorials'''.

# Assuming the character you want to animate isn't in your rig file, then using OniSplit, export any character you want as a DAE (-extract:dae) using -noanim and -blender arguments.
## As per EdT's '''Oni-Blender Tutorial''', you should get <tt>AnimationDaeWriter: custom axis conversion</tt> in OniSplit output if you've used the -blender argument. If you didn't get that on the output, it means something most likely went wrong and you won't be able to import the model into Blender (or you will be able to import it but it will be wrong).
## Assuming you wanted a textured model and thus you've exported an ONCC, you should now get a '''DAE file''' and an '''''images''''' folder containing the textures for it.
# Using OniSplit, export the animation you want as an XML (-extract:xml) using -anim-body (lets you specify the character you want) and -blender arguments.
## You should get '''one DAE and one XML file for the animation.'''
# Open up a Blender scene containing the rig.
# Delete either the model either in Pose1 or Pose2 collection.
# Import the animation into Blender ('''MAKE SURE YOU CHECK THE ''Import Unit'' BOX EACH TIME''', otherwise you will import the model with arbitrary units which will break everything and will be basically unadjustable later))
# Import the -noanim model into Blender ('''ALSO MAKE SURE YOU CHECK THE ''Import Unit'' BOX''')
# Move the animated model to either Pose1 or Pose2 collection.
# If you've imported the textured model, [[Blender#Lack_of_textures_on_animated_models|apply textures to the animated models and fix the alpha transparency issue]].

==Added functionalities==
This header describes functionalities added to the rig by geyser that are not normally present in Rigify.

===Pose matching===
The way we do animations is we almost universally start by copying the first or last frame of the preceeding animation. For this reason, we needed functionality that would allow us to snap the rig to an animated Oni character. The way it works, it that it uses bone constraints in rig controller bones targeting the character model in order to snap the rig to the model. The influence of the bone constraints is controlled through the Z location of Pose1 and Pose2 bones in the Pose Matching layer, which is done through drivers.

To snap the rig to the animation in one of the Pose collections, simply move the appropriate Pose bone above the XY plane while in Pose mode.

{| class="wikitable"
|-
! Pose1 and Pose2 below the XY plane !! Rig snapped to the animation in Pose 1 collection !! Rig snapped to the animation in Pose 2 collection
|-
| [[Image:Unposed.png|300px|frameless|center]] || [[Image:Pose1.png|300px|frameless|center]] || [[Image:Pose2.png|300px|frameless|center]]
|-
|}

===Wrist snapping===
Often when using the IK handles for the arms you will find out that most of the time, you will need the hand to have the same rotation as the forearm. Normally this would mean that you would have to rotate the hands all the time, because IK handles are mainly moved around, and rotated later. For this reason, the wrist snapping functionality was implemented - you can simply copy the rotation of the forearm to the hand by pressing the "IK wrist" button.
{| class="wikitable"
|-
! Both of the hands after just moving them around... !! Effects of using the IK Wrist button
|-
| [[Image:IK Wrist Example1.png|500px|frameless|center]] || [[Image:IK Wrist Example2.png|500px|frameless|center]]
|-
|}

[[Category:Modding tutorials]]

BlenderOni

2022-05-18T15:24:16Z

Delano762: Added image of the BlenderOni panel

{|style="float:right"
|[[Image:BlenderOni.png|thumb|130px|BlenderOni version 1.0.1]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|''Note to self: no more pizza before bed! Nightmares!'' ]]
|}
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Tutorial video==
BlenderOni has its own tutorial video, with the Options explained in Part 2, and Use cases explained in Part 3.

The video can be accessed [https://www.youtube.com/watch?v=pA_Y8QBCvPI HERE].

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed. '''Use in Object Mode.'''

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode. '''Use in Object Mode.'''

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws. '''Use in Object Mode.'''

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any object interaction mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

File:BlenderOni.png

2022-05-18T15:19:34Z

Delano762: Delano762 uploaded a new version of File:BlenderOni.png

== Summary ==
BlenderOni version 1.0.1

File:BlenderOni.png

2022-05-18T15:18:33Z

Delano762: BlenderOni version 1.0.1

== Summary ==
BlenderOni version 1.0.1

BlenderOni

2022-05-18T15:07:41Z

Delano762: /* Use cases */ Added link to the tutorial video

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed. '''Use in Object Mode.'''

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode. '''Use in Object Mode.'''

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws. '''Use in Object Mode.'''

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any object interaction mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

===Tutorial video===
BlenderOni has its own tutorial video, with the Options header explained in Part 2, and Use cases explained in Part 3.

The video can be accessed [https://www.youtube.com/watch?v=pA_Y8QBCvPI HERE].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T15:03:21Z

Delano762: /* Adjust Throw Target */

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed. '''Use in Object Mode.'''

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode. '''Use in Object Mode.'''

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws. '''Use in Object Mode.'''

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any object interaction mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T15:02:51Z

Delano762: /* Options */ Added intended object interaction modes.

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed. '''Use in Object Mode.'''

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode. '''Use in Object Mode.'''

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range. '''Use in Object Mode.'''
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any object interaction mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T15:01:46Z

Delano762: /* Constrain Character Model */

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any object interaction mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T15:01:21Z

Delano762: /* Constrain Character Model */

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig. '''Can be used in any Object Interaction Mode.'''

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T14:58:09Z

Delano762: /* Use cases */ Link to rig documentation.

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig.

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
Since BlenderOni is a companion tool for the Rigify-Oni rig, explanation of its intended usage is in the rig documentation, available [[Using_the_Rigify_animation_rig|HERE]].

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-18T14:47:07Z

Delano762: /* Constrain Character Model */ Explains

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===
On the selected Oni character model, creates a set of Copy Location and Copy Rotation constraints targeting a specified rig. Effectively constrains the selected Oni character model to the specified rig.

If any of the model objects already contain any constrains, BlenderOni will output an error, and the user should clear all constraints in the selected objects.

==Use cases==
To be further described, but probably best to link to the [[Using_the_Rigify_animation_rig|rig documentation]]

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-17T15:55:01Z

Delano762: /* Bone Visual Transformer */

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the armature in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===

==Use cases==
To be further described, but probably best to link to the [[Using_the_Rigify_animation_rig|rig documentation]]

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-17T15:54:43Z

Delano762: /* Set Object Constraint Targets */

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the aramture in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig. '''Use in Object Mode.'''

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===

==Use cases==
To be further described, but probably best to link to the [[Using_the_Rigify_animation_rig|rig documentation]]

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-17T15:54:10Z

Delano762: /* Options */ Explained more options

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|150px|Note to self: no more pizza before bed! Nightmares! ]]
|}
'''BlenderOni''' is a [[Blender]] add-on intended as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender]]. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the add-on's options can also be used for general Blender tasks.

'''BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]'''

==History==
When the Rigify-Oni rig was first released to the public, it was meant to be used together with a number of scripts stored within the Blender scene containing the rig. However, those scripts were not ideal - they were awkward to use as setting up the appropriate values was possible only by changing the script code.

Those scripts have become obsolete with the introduction of BlenderOni, which is essentially little more than those scripts wrapped into a GUI. The scripts are nonetheless archived [[Blender/Obsolete scripts|HERE]] for legacy purposes.

==Options==
===Bake Keyframe Rotation Mode===
Keyframes the rotation data in the selected rotation mode for every selected object, for every frame in the specified frame range. Usually used for converting rotation data from Euler angles to Quaternions if needed.

===Change Rotation Mode===
Changes the rotation mode of every selected object to the selected rotation mode.

===Adjust Throw Target===
Moves the selected object by the specified offset for every frame in the specified frame range.
If the "Adjust and rotate throw target" operation is selected, the object will also get rotated by 180 degrees in the frame range.
If the "Adjust back throw target" operation is selected and the object's location is not { X , Y } = { 0 , 0 }, it gets moved to { X , Y } = { 0 , 0 }.

Used for adjusting the position of the throw target animation, both for forward (Adjust and rotate throw target) and back (Adjust back throw target) throws.

If you are importing an animation from Oni, the X, Y and Z fields are supposed to be taken from the <Position> tag. The position tag has the following order:

<pre><Position>x y z</Position></pre>

BlenderOni takes them in a different order due to differences in axis orientation:
<pre> X: x, Y: -z, Z: -y</pre>

So given the following <Position> tag with the following example values:
<pre><Position>1 2 -3</Position></pre>

The arguments in BlenderOni should be as follows:
<pre> X: 1, Y: 3, Z: -2</pre>

If you have created a new animation and want to adjust it back to { X , Y } = { 0 , 0 }, then the X and Y arguments will be the inversions of the X and Y location coordinates of the throw target's pelvis in the first frame of the animation. Z should be set to 0. The new resulting <Position> tag should be created using the order schematic above, with the exception of the height (Blender Z, <Position> y) - this value is mostly taken from other TRAMs and adjusted in a trial-and-error manner until the animation looks okay on most characters.

This is because the height adjustment is one and the same for every character type, regardless of their height - so if you pick the right height, smaller characters will float off the ground and the tallest ones will sink into it, while average height characters should have their feet on the ground.

===Object Constraint Switch===
Switches object constraints on and off within selected objects. Used to constrain and unconstrain character model objects to the rig. '''Use in Object Mode.'''

===Bone Constraint Switch===
Switches bone constraints on and off within selected armature bones. Used to constrain and unconstrain rig to character model objects. '''Use in Pose Mode.'''

===Object Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected object in the specified frame range. Used as a way to copy animation data from the rig to the character models. '''Use in Object Mode.'''

===Bone Visual Transformer===
Applies visual transform and keyframes rotation and location data for every selected bone of the aramture in the specified frame range. Used as a way to copy animation data from character models to the rig. '''Use in Pose Mode.'''

===Set Object Constraint Targets===
Sets the targets of all of the constraints named "Copy Rotation", and also "Copy Location" in case of pelvis, to the specified object. Used to constrain the selected character model to the specified rig.

===Set Rig Bone Constraint Targets===
In the specified rig, sets the target names of predefined bone constraints with names ending in one of the selected suffixes (.001 or .002) to the appropriate Oni character model object name with the specified suffix. Used to constrain rigs to the character models. '''Can be used in any object interaction mode.'''

To explain more clearly: The Rigify-Oni rig has two sets of bone constraints of Copy Location for the torso and torso_pivot bone, and Copy Rotation for all of the remaining bones in the FK and Torso layers. They are responsible for copying rotation and location data from the targeted character models, with the influence of those constraints being controlled with the corresponding Pose Matching bones (Pose1 for .001 constraints and Pose2 for .002). The character models will always have their body objects named the same way (pelvis, torso, chest, etc.), and because of that, Blender adds suffixes to their names as more characters are imported, starting with ".001" suffix.

Because of this, the way to constrain an instance of the Rigify-Oni rig to the given character model is to set the target names of the .001 or .002 bone constraint targets to the appropriate Oni character model objects with the appropriate suffix. (BlenderOni has the Oni character model object names hardcoded, it only needs their suffix)

Example: You want to constrain rig.001, to the character model with .003 suffix through the rig's .002 bone constraints. To do that, you need to:
*Input rig.001 as the target rig name,
*Select .002 as the Bone constraints' suffix,
*Input .003 as the Target objects' suffix,
*Press Set Rig Bone Constraints Targets.
*Make sure Pose1 bone is below the floor level (Y<0)
*Make sure Pose2 bone is above the floor level (Y>0.1)

Rig.001 will now be constrained to the Oni character model with .003 suffix.

===Constrain Character Model===

==Use cases==
To be further described, but probably best to link to the [[Using_the_Rigify_animation_rig|rig documentation]]

[[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

BlenderOni

2022-05-16T20:56:09Z

Delano762: /* Options */ Described first three options

Using the Rigify animation rig

2022-05-16T09:19:55Z

Delano762: /* Optional tools and tutorials */

==Introduction==
This article is intended to explain the workflow of using the [http://mods.oni2.net/node/388 Rigify-based animation rig for Blender] (made by geyser) for the purpose of making Oni animations, and also how to use it, and what are the Oni-specific additions to it that we've made.

==Prerequisite tutorials==
As this rig is now intented to be used together with BlenderOni, it is necessary to be familiar with either:
* [[BlenderOni|BlenderOni's documentation,]]
* [https://www.youtube.com/watch?v=pA_Y8QBCvPI BlenderOni's explanatory video,] particularly time ranges from 0:00 - 3:07 and 21:24 - 48:05 (that's part 1 and 3 of the video).

Besides that, I highly recommend watching the tutorials below if you feel you're lacking knowledge in any of these subjects:

General Blender basics:

* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins]

Practical and intuitive explanation of what Inverse and Forward Kinematics (IK/FK) are - this is explained in Maya, but same principles apply in every 3D editing program including Blender:
* [https://www.youtube.com/watch?v=p6PYKyxR0aY Animating with IK and FK]

Basics of using Rigify - '''all you need to know about animating with Rigify is stored in the video below.''' There is no point in making a tutorial on how to use the rig controllers themselves here - it's all in the video below:

* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify Tutorial #08 - Posing the Rigify rig] by CGDive

(OPTIONAL) Tutorial on how to create the rig described here - this is strictly optional; the only practical reason to make your own rig is for the purpose of adjusting its controllers to a specific character, however, the advantage that you get out of that is purely visual and a marginal one at that - if you've built your rig for Konoko, there's nothing stopping you from using it on a TCTF SWAT - the limb controllers will be only slightly out of place, which doesn't impact animating in any way. So ultimately you may want to go through this if you want to learn how this rig works, find this rig confusing, or even just for the bunch of great Youtube tutorials linked in that tutorial.

Also, it's worth noting that a huge part of this article is in fact copy-pasted from this tutorial.

* [[Creating_an_animation_rig_in_Blender|Creating an animation rig in Blender]]

==Required tools and commands==
There are several things worth knowing before you start creating the rig, tools to get and tutorials to have ready to reference for commands.

===Tools and relevant tutorials===
* '''[[BlenderOni|BlenderOni]]''' - this Blender addon is an integral companion tool for this rig - it contains a number of scripts which automate a lot of operations required to make any use out of the rig. Without those scripts, these operations (e.g. constraining the model to the rig and vice versa) would have to be done manually, which takes a ridiculous amount of time.
[[Image:Cmder.png|200px|right|thumb|Screenshot showing Cmder's capabilities within the context of modding Oni]]
* [http://mods.oni2.net/node/38 '''Current version of OniSplit.'''] This is the tool needed to import and export assets out of Oni. '''DO NOT USE OniSplit GUI or Vago for importing Oni assets into Blender''' - neither of these weren't updated in a long time, and thus they don't support OniSplit's v0.9.99.2 -blender option. You can still use them for other purposes though, such as sounds and converting .oni files to XMLs, etc.
* [https://docs.google.com/document/d/175uJGklYASAgrFjxuUG4-kJRDoMTjjP7GvNxSj1GscU/edit '''Oni-Blender tutorial'''] by EdT. Please read this in entirety to know likely-to-happen issues and refer to this as your guide for OniSplit commands relating to Blender.
* [http://oni.bungie.org/forum/viewtopic.php?pid=23230#p23230 '''Brief overview on creating TRAMs'''] by EdT - while this was written with XSI in mind, this is still relevant as the process for preparing the XML files for Oni is still the same. Also the next post in that thread, called '''Brief walk through on modifying a TRAM,''' is an example of that overview put into practice.

===Optional tools and tutorials===
* [https://cmder.net/ '''Cmder'''] (Windows only) - because OniSplit is a command line tool, it is highly recommended to get any upgrade to Windows' Command Prompt. As shown in the screenshot on the right, Cmder allows you to start it from the context menu in any selected folder, and it also remembers your most recently used commands, vastly improving your workflow when you're forced to use any command line tools.
* [https://docs.blender.org/manual/en/2.81/addons/rigging/rigify.html '''Rigify documentation'''] - it's a plugin for Blender designed to automate a lot of rigging work. The rig described here is generated using Rigify. Take a look if you're interested and want to learn more, but you don't have to know Rigify's documentation to use this rig.

==General workflow of animating for Oni using Rigify==
The general workflow of making animations using this rig is the following, assuming you want to make a single animation (i.e. you don't want to make a throw animation):

# Open up a Blender scene containing the rig.
# Delete either the model in Pose1 or Pose2.
# (OPTIONAL) Assuming you want to animate a different character, delete the T-posed model.
## Import your desired character with textures using -noanim.
# Import the animation you are using as a starting point. For more detailed information on how to import an Oni animation to Blender, see the next header.
## If you did point 3, apply the textures on the animated model.
# Using the ''Set Rig Bone Constraint Targets'' option in BlenderOni, set the targets of the rig's bone constraints to be the body parts of the animation you've imported.
# Using the Pose Matching functionality, constrain the rig to the imported animation (Set the IK-FK sliders on rig limbs to 1, as Pose Matching works only through FK controllers)
# For each frame that you want to remain in your animation, while having all the bones selected (or the ones you want), either:
## Press Ctrl+A, select ''Apply Visual Transform'' to Pose and keyframe it,
## Or use the ''Bone Visual Transformer'' option in BlenderOni to bake frames within a specified frame range.
# Disable bone constraints on the rig using the ''Bone Constraint Switch'' option in BlenderOni.
# '''Make your animation.'''
# Once your animation is ready, use the ''Object Visual Transformer'' option in BlenderOni to bake the rig keyframes into the character model.
# Using the ''Object Constraint Switch'' option in BlenderOni, disable the object constraints on the character model. '''The character model should now be animated and have the needed rotations and locations.
# Export the animation as a DAE.

==Importing Oni animations to Blender==
This header describes how to import Oni animations to Blender.

For detailed explanation of the required OniSplit commands, please refer to the '''Oni-Blender Tutorial by EdT''' listed in the '''Tools and relevant tutorials'''.

# Assuming the character you want to animate isn't in your rig file, then using OniSplit, export any character you want as a DAE (-extract:dae) using -noanim and -blender arguments.
## As per EdT's '''Oni-Blender Tutorial''', you should get <tt>AnimationDaeWriter: custom axis conversion</tt> in OniSplit output if you've used the -blender argument. If you didn't get that on the output, it means something most likely went wrong and you won't be able to import the model into Blender (or you will be able to import it but it will be wrong).
## Assuming you wanted a textured model and thus you've exported an ONCC, you should now get a '''DAE file''' and an '''''images''''' folder containing the textures for it.
# Using OniSplit, export the animation you want as an XML (-extract:xml) using -anim-body (lets you specify the character you want) and -blender arguments.
## You should get '''one DAE and one XML file for the animation.'''
# Open up a Blender scene containing the rig.
# Delete either the model either in Pose1 or Pose2 collection.
# Import the animation into Blender ('''MAKE SURE YOU CHECK THE ''Import Unit'' BOX EACH TIME''', otherwise you will import the model with arbitrary units which will break everything and will be basically unadjustable later))
# Import the -noanim model into Blender ('''ALSO MAKE SURE YOU CHECK THE ''Import Unit'' BOX''')
# Move the animated model to either Pose1 or Pose2 collection.
# If you've imported the textured model, [[Blender#Lack_of_textures_on_animated_models|apply textures to the animated models and fix the alpha transparency issue]].

==Added functionalities==
This header describes functionalities added to the rig by geyser that are not normally present in Rigify.

===Pose matching===
The way we do animations is we almost universally start by copying the first or last frame of the preceeding animation. For this reason, we needed functionality that would allow us to snap the rig to an animated Oni character. The way it works, it that it uses bone constraints in rig controller bones targeting the character model in order to snap the rig to the model. The influence of the bone constraints is controlled through the Z location of Pose1 and Pose2 bones in the Pose Matching layer, which is done through drivers.

To snap the rig to the animation in one of the Pose collections, simply move the appropriate Pose bone above the XY plane while in Pose mode.

{| class="wikitable"
|-
! Pose1 and Pose2 below the XY plane !! Rig snapped to the animation in Pose 1 collection !! Rig snapped to the animation in Pose 2 collection
|-
| [[Image:Unposed.png|300px|frameless|center]] || [[Image:Pose1.png|300px|frameless|center]] || [[Image:Pose2.png|300px|frameless|center]]
|-
|}

===Wrist snapping===
Often when using the IK handles for the arms you will find out that most of the time, you will need the hand to have the same rotation as the forearm. Normally this would mean that you would have to rotate the hands all the time, because IK handles are mainly moved around, and rotated later. For this reason, the wrist snapping functionality was implemented - you can simply copy the rotation of the forearm to the hand by pressing the "IK wrist" button.
{| class="wikitable"
|-
! Both of the hands after just moving them around... !! Effects of using the IK Wrist button
|-
| [[Image:IK Wrist Example1.png|500px|frameless|center]] || [[Image:IK Wrist Example2.png|500px|frameless|center]]
|-
|}

[[Category:Modding tutorials]]

Blender

2022-05-16T08:57:27Z

Delano762: /* History of modding with Blender */ It's not that rigging never worked in XSI, it's that we've never figured it out there. Also minor grammatical edits.

Blender is a free and open-source program used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of modding with Blender==
[[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009, had the fewest problems in handling Oni's assets and animations, it was relatively easy to learn and use. Up until 2019, it was Oni community's 3D program of choice.

Blender at that time had a notoriously bad user interface and couldn't handle DAE files very well. [[#Oni-specific_issues_with_Blender|Besides other problems]], most importantly the expected rotation order and up-axis were different between XSI and Blender.

After an interface overhaul in version 2.80 Blender's user-friendliness and [http://oni.bungie.org/forum/viewtopic.php?pid=52588#p52588 support for vertex shading in DAE] was improved. At the same time more and more users had problems to run XSI on their PCs.

By 2019 demands got louder to support Blender made animations. [[OniSplit]] received an update (<tt>-blender</tt>) so it could read such animations. Also, rigging was never fully figured out in XSI so between 2020 and 2022 an [[Using the Rigify animation rig|animation rig]] tailor-fit for making Oni animations - alongside a new addon named [[BlenderOni]] - was created. It was the last nail in the coffin of XSI.

==Tutorials and resources==
With the abundance of tutorials for Blender on YouTube, creating our own introductory material would be reinventing the wheel. So instead we recommend watching some of the tutorials listed below and trying to make small personal projects in order to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (don't be misled by the silly name - this is one of the best Blender basics tutorials out there; it's also good if you know your basics already and you want to find out if you've missed anything)

Modelling:
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging:
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation:
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to what you might expect, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! (Curtis Holt)]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners (Jayanam)]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using the Rigify animation rig|HERE]]. The rig is based on the Rigify plugin for Blender and serves as the '''community's modern tool to create new character animations for Oni''', featuring both Forward and Inverse Kinematics – an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it – '''without it, the rig is extremely difficult to set up, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intended as an integral companion tool for the fan-made animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender. If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ"; this is because Blender reads the Euler angles [https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html from the bottom of the hierarchy] rather than the top. In other words, Oni reads XYZ starting with X, while Blender starts with Z.

You can demonstrate this by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below. The image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Differing up-axis===
To be expanded on later: Oni's "up" axis is Y, Blender's is Z.

===Units===
To be expanded on later: Oni's units are in the imperial system, not the metric one, though the 0.1-meter unit used by OniSplit is a good approximation of Oni's actual world unit of 4 inches.

===Lack of textures on animated models===
'''Currently there is no option in OniSplit for exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in the case of Oni; the models are low-detail to a point where you can lose sense of which direction elbows and knees are facing if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually in the Shading tab.

{| class="wikitable"
|-
! Copying materials
|-
| [[Image:ABR_Copying_materials.png|200px|frameless|center]]
|-
|}

===Alpha transparency issue===
You will also most likely need to set the Shading settings on some of the body parts of a non-animated model in order to fix alpha transparency issues (much like in XSI); specifically, you'll need to connect the Alpha parameter of the Base Color node to any parameter in Principled BSDF that will work, such as Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how to do so at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]]
|-
|}

==Wanted==
Except for sounds, textures and text-oriented resources, Blender has the potential to be THE editor for Oni. Its powerful Python support is very useful for customization.

Additional imports/exports, XML/.oni file creation and configurations should be automated, and customization should be used to streamline workflows as much as possible. Tools in the form of addons should allow users to be artists instead of coders, speeding up development of the actual projects.

A successful modding community requires not one of these points, but all of them: documentation, tools and tutorials.

===Level editor===
* core geometry
* pathfinding
* "furniture" (OFGA) creation/placement
* editing of CJBO
* special gunk flag placement
* basic level shading (vertex shading)
* advanced level shading for OniX?

'''OFGA library'''

Objects that are used pretty often should be provided either by Blender Asset Browser or by a customized solution.
* Blender Asset Browser video demo: https://www.youtube.com/watch?v=gJC0y6HqyAU

===BSL editor===
Most events in Oni are fired using trigger volumes. There should be an editor to open the code of a trigger volume as soon as it's selected in Blender.

Also, character functions should editable when you select a character.

The editor should be context-sensitive to:
* level geometry: atmosphere, save points, win level, lose level
* objects: scripting of static and animated objects (cutscene editor)
* particle scripting
* character: after selecting a character there should be a button visible to edit the ONCC, TRBS, animations and textures (GIMP/Photoshop).

===Character editor===

'''Character library'''

There should be a way to place characters or character placeholders so that character collections (BINACHAR) can be saved to disk based on their positioning in the level model.

===Animation editor===
The core would be BlenderOni that is called as soon as a user chooses to create or edit an animation. It could be extended to edit TRAC.

===Particle editor===
A particle editor has been always missing in the community.

===Testing and publishing support===
There should be some linking to Vago and AEI for package creation and quick starting of levels for testing.

A secondary Oni installation could serve as a developer environment where only one level is present at a time. With OniX, it could be made possible to skip the menu UI and automatically load the current project.

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

BlenderOni

2022-05-15T21:48:36Z

Delano762: Added Options, Use cases, changed History a bit

Blender

2022-05-15T19:12:21Z

Delano762: /* Tutorials and resources */

Blender is a free and open-source program used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of modding with Blender==
Up until 2019, the Oni community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. But Softimage was discontinued in 2014, so the community was using increasingly outdated software. XSI was the only free software that the community could make any sense of (although very limited), and it had no problems handling Oni's assets and animations, unlike other programs. Blender was overlooked because, despite its popularity, its user interface was notoriously bad. Also, attempts at importing Oni's assets to Blender ran into [[#Oni-specific_issues_with_Blender|a number of issues]] with unknown causes.

However, Blender's user interface received a total overhaul in version 2.80 which was universally praised. The program has become a serious free alternative to industry-standard 3D programs like Maya or 3ds Max. This, along with the considerations that Blender continues to be actively developed, is a light-weight program, supports Macs as well as Windows, and has an abundance of support from the Blender community, eventually made it clear that Oni modders needed to move on from XSI to Blender. The final nails in the coffin were XSI's lack of stability and a limited amount of resources and tutorials to work with.

From 2020 to 2022, a significant amount of work was done to allow modding Oni in Blender: the <tt>-blender</tt> tag was introduced to [[OniSplit]], and a new [[Using the Rigify animation rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] – a companion tool for said rig. With all of this done, the community can now create new content for Oni in a modern, free, well-supported 3D modeler.

==Tutorials and resources==
With the abundance of tutorials for Blender on YouTube, creating our own introductory material would be reinventing the wheel. So instead we recommend watching some of the tutorials listed below and trying to make small personal projects in order to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (don't be misled by the silly name - this is one of the best Blender basics tutorials out there; it's also good if you know your basics already and you want to find out if you've missed anything)

Modelling:
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging:
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation:
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to what you might expect, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! (Curtis Holt)]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners (Jayanam)]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using the Rigify animation rig|HERE]]. The rig is based on the Rigify plugin for Blender and serves as the '''community's modern tool to create new character animations for Oni''', featuring both Forward and Inverse Kinematics – an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it – '''without it, the rig is extremely difficult to set up, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intended as an integral companion tool for the fan-made animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender. If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ"; this is because Blender reads the Euler angles [https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html from the bottom of the hierarchy] rather than the top. In other words, Oni reads XYZ starting with X, while Blender starts with Z.

You can demonstrate this by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below. The image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Differing up-axis===
To be expanded on later: Oni's "up" axis is Y, Blender's is Z.

===Units===
To be expanded on later: Oni's units are in the imperial system, not the metric one, though the 0.1-meter unit used by OniSplit is a good approximation of Oni's actual world unit of 4 inches.

===Lack of textures on animated models===
'''Currently there is no option in OniSplit for exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in the case of Oni; the models are low-detail to a point where you can lose sense of which direction elbows and knees are facing if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually in the Shading tab.

{| class="wikitable"
|-
! Copying materials
|-
| [[Image:ABR_Copying_materials.png|200px|frameless|center]]
|-
|}

===Alpha transparency issue===
You will also most likely need to set the Shading settings on some of the body parts of a non-animated model in order to fix alpha transparency issues (much like in XSI); specifically, you'll need to connect the Alpha parameter of the Base Color node to any parameter in Principled BSDF that will work, such as Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how to do so at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]]
|-
|}

==Wanted==
Except for sounds, textures and text-oriented resources, Blender has the potential to be THE editor for Oni. Its powerful Python support is very useful for customization.

Additional imports/exports, XML/.oni file creation and configurations should be automated, and customization should be used to streamline workflows as much as possible. Tools in the form of addons should allow users to be artists instead of coders, speeding up development of the actual projects.

A successful modding community requires not one of these points, but all of them: documentation, tools and tutorials.

===Level editor===
* core geometry
* pathfinding
* "furniture" (OFGA) creation/placement
* editing of CJBO
* special gunk flag placement
* basic level shading (vertex shading)
* advanced level shading for OniX?

'''OFGA library'''

Objects that are used pretty often should be provided either by Blender Asset Browser or by a customized solution.
* Blender Asset Browser video demo: https://www.youtube.com/watch?v=gJC0y6HqyAU

===BSL editor===
Most events in Oni are fired using trigger volumes. There should be an editor to open the code of a trigger volume as soon as it's selected in Blender.

Also, character functions should editable when you select a character.

The editor should be context-sensitive to:
* level geometry: atmosphere, save points, win level, lose level
* objects: scripting of static and animated objects (cutscene editor)
* particle scripting
* character: after selecting a character there should be a button visible to edit the ONCC, TRBS, animations and textures (GIMP/Photoshop).

===Character editor===

'''Character library'''

There should be a way to place characters or character placeholders so that character collections (BINACHAR) can be saved to disk based on their positioning in the level model.

===Animation editor===
The core would be BlenderOni that is called as soon as a user chooses to create or edit an animation. It could be extended to edit TRAC.

===Particle editor===
A particle editor has been always missing in the community.

===Testing and publishing support===
There should be some linking to Vago and AEI for package creation and quick starting of levels for testing.

A secondary Oni installation could serve as a developer environment where only one level is present at a time. With OniX, it could be made possible to skip the menu UI and automatically load the current project.

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-15T18:45:47Z

Delano762: Deleted the Blender 3.1 information box, changed "add-on" to "addon", moved "Copying Materials" image to "Lack of textures on animated models" paragraph, deleted "Setting materials in Shading" as it was a duplicate for some reason

Blender is a free and open-source program used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of modding with Blender==
Up until 2019, the Oni community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. But Softimage was discontinued in 2014, so the community was using increasingly outdated software. XSI was the only free software that the community could make any sense of (although very limited), and it had no problems handling Oni's assets and animations, unlike other programs. Blender was overlooked because, despite its popularity, its user interface was notoriously bad. Also, attempts at importing Oni's assets to Blender ran into [[#Oni-specific_issues_with_Blender|a number of issues]] with unknown causes.

However, Blender's user interface received a total overhaul in version 2.80 which was universally praised. The program has become a serious free alternative to industry-standard 3D programs like Maya or 3ds Max. This, along with the considerations that Blender continues to be actively developed, is a light-weight program, supports Macs as well as Windows, and has an abundance of support from the Blender community, eventually made it clear that Oni modders needed to move on from XSI to Blender. The final nails in the coffin were XSI's lack of stability and a limited amount of resources and tutorials to work with.

From 2020 to 2022, a significant amount of work was done to allow modding Oni in Blender: the <tt>-blender</tt> tag was introduced to [[OniSplit]], and a new [[Using the Rigify animation rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] – a companion tool for said rig. With all of this done, the community can now create new content for Oni in a modern, free, well-supported 3D modeler.

==Tutorials and resources==
With the abundance of tutorials for Blender on YouTube, creating our own introductory material would be reinventing the wheel. So instead we recommend watching some of the tutorials listed below and trying to make small personal projects in order to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (don't get this is one of the best Blender basics tutorials out there; it's also good if you know your basics already and you want to find out if you've missed anything)

Modelling:
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging:
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation:
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to what you might expect, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! (Curtis Holt)]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners (Jayanam)]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using the Rigify animation rig|HERE]]. The rig is based on the Rigify plugin for Blender and serves as the '''community's modern tool to create new character animations for Oni''', featuring both Forward and Inverse Kinematics – an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it – '''without it, the rig is extremely difficult to set up, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intended as an integral companion tool for the fan-made animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, the vast majority of the addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender. If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ"; this is because Blender reads the Euler angles [https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html from the bottom of the hierarchy] rather than the top. In other words, Oni reads XYZ starting with X, while Blender starts with Z.

You can demonstrate this by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below. The image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Differing up-axis===
To be expanded on later: Oni's "up" axis is Y, Blender's is Z.

===Units===
To be expanded on later: Oni's units are in the imperial system, not the metric one, though the 0.1-meter unit used by OniSplit is a good approximation of Oni's actual world unit of 4 inches.

===Lack of textures on animated models===
'''Currently there is no option in OniSplit for exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in the case of Oni; the models are low-detail to a point where you can lose sense of which direction elbows and knees are facing if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually in the Shading tab.

{| class="wikitable"
|-
! Copying materials
|-
| [[Image:ABR_Copying_materials.png|200px|frameless|center]]
|-
|}

===Alpha transparency issue===
You will also most likely need to set the Shading settings on some of the body parts of a non-animated model in order to fix alpha transparency issues (much like in XSI); specifically, you'll need to connect the Alpha parameter of the Base Color node to any parameter in Principled BSDF that will work, such as Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how to do so at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]]
|-
|}

==Wanted==
Except for sounds, textures and text-oriented resources, Blender has the potential to be THE editor for Oni. Its powerful Python support is very useful for customization.

Additional imports/exports, XML/.oni file creation and configurations should be automated, and customization should be used to streamline workflows as much as possible. Tools in the form of addons should allow users to be artists instead of coders, speeding up development of the actual projects.

A successful modding community requires not one of these points, but all of them: documentation, tools and tutorials.

===Level editor===
* core geometry
* pathfinding
* "furniture" (OFGA) creation/placement
* editing of CJBO
* special gunk flag placement
* basic level shading (vertex shading)
* advanced level shading for OniX?

'''OFGA library'''

Objects that are used pretty often should be provided either by Blender Asset Browser or by a customized solution.
* Blender Asset Browser video demo: https://www.youtube.com/watch?v=gJC0y6HqyAU

===BSL editor===
Most events in Oni are fired using trigger volumes. There should be an editor to open the code of a trigger volume as soon as it's selected in Blender.

Also, character functions should editable when you select a character.

The editor should be context-sensitive to:
* level geometry: atmosphere, save points, win level, lose level
* objects: scripting of static and animated objects (cutscene editor)
* particle scripting
* character: after selecting a character there should be a button visible to edit the ONCC, TRBS, animations and textures (GIMP/Photoshop).

===Character editor===

'''Character library'''

There should be a way to place characters or character placeholders so that character collections (BINACHAR) can be saved to disk based on their positioning in the level model.

===Animation editor===
The core would be BlenderOni that is called as soon as a user chooses to create or edit an animation. It could be extended to edit TRAC.

===Particle editor===
A particle editor has been always missing in the community.

===Testing and publishing support===
There should be some linking to Vago and AEI for package creation and quick starting of levels for testing.

A secondary Oni installation could serve as a developer environment where only one level is present at a time. With OniX, it could be made possible to skip the menu UI and automatically load the current project.

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-14T17:28:00Z

Delano762: /* Oni-specific issues with Blender */ Updated info on rotation order issues backing it up with Blender manual, also added ""Up" axis problem" and "Units" subheaders

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender, and serves as the '''community's modern tool to create new character animations for Oni,''' featuring both Forward and Inverse Kinematics, thus being an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intented as an integral companion tool for the Animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, vast majority of addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ" - and this is because Blender reads the Euler angles from the bottom of the hierarchy, rather than the top:

{{Quote|Which axis is on top, which one in the middle and which at the bottom, depends on the particular Euler gimbal: there are six types of them, as there are six possible combinations: XYZ, XZY, YXZ, YZX, ZXY and ZYX Euler rotation modes. '''These modes are named using the letters of the axes in order, starting from the axis at the bottom of the hierarchy, and finishing with the one on top.'''|[https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html Blender Manual, Rotation Modes] }}

In other words, Oni reads XYZ as X first, Y second and then finally Z, while Blender does reverse, it reads XYZ as Z first, Y second and Z as the last angle.

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

==="Up" axis problem===
To be further described, Oni's up axis is Y, for Blender it's Z

===Units===
To be further described, Oni's units are actually feet and yards

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-14T17:14:29Z

Delano762: /* Rotation order issue between Oni and Blender */ Updated info on rotation order issue between Oni and Blender

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender, and serves as the '''community's modern tool to create new character animations for Oni,''' featuring both Forward and Inverse Kinematics, thus being an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intented as an integral companion tool for the Animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, vast majority of addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ" - and this is because Blender reads the Euler angles from the bottom of the hierarchy, rather than the top:

{{Quote|Which axis is on top, which one in the middle and which at the bottom, depends on the particular Euler gimbal: there are six types of them, as there are six possible combinations: XYZ, XZY, YXZ, YZX, ZXY and ZYX Euler rotation modes. '''These modes are named using the letters of the axes in order, starting from the axis at the bottom of the hierarchy, and finishing with the one on top.'''|[https://docs.blender.org/manual/en/latest/advanced/appendices/rotations.html Blender Manual, Rotation Modes] }}

In other words, Oni reads XYZ as X first, Y second and then finally Z, while Blender does reverse, it reads XYZ as Z first, Y second and Z as the last angle.

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-14T16:56:02Z

Delano762: /* BlenderOni */ Filled BlenderOni

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender, and serves as the '''community's modern tool to create new character animations for Oni,''' featuring both Forward and Inverse Kinematics, thus being an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
BlenderOni is a Blender addon intented as an integral companion tool for the Animation rig for Blender. It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, vast majority of addon's options can also be used for general Blender purposes.

For more information on BlenderOni, please check its documentation page available [[BlenderOni|HERE]].

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ".

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

BlenderOni

2022-05-14T16:54:28Z

Delano762: Added Scripts header

{|style="float:right"
|[[Image:Guido_-_Kon_face_07.jpg|thumb|300px|Note to self: no more pizza before bed! Nightmares! ]]
|}
BlenderOni is a [[Blender|Blender]] addon intented as an integral companion tool for the [[Using_the_Rigify_animation_rig|Animation rig for Blender.]] It contains functionalities that automate a lot of operations necessary for the rig to function and be used properly. However, vast majority of addon's options can also be used for general Blender purposes.

BlenderOni can be downloaded [http://mods.oni2.net/node/401 HERE.]

==Scripts==
We used a number of scripts for the purpose of making the Rigify Oni rig usable, however those scripts have become obsolete with the introduction of the BlenderOni - BlenderOni is essentially little more than those scripts wrapped into a GUI. They are nonetheless archived [[Blender/Obsolete_scripts|HERE]] for legacy purposes.

[[Category:Modding tutorials]][[Category:Completed modding tools]][[Category:Bi-platform modding tools]]

Blender

2022-05-14T16:36:51Z

Delano762: /* Animation rig with IK and FK */ change to the first paragraph of this header

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have an animation rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender, and serves as the '''community's modern tool to create new character animations for Oni,''' featuring both Forward and Inverse Kinematics, thus being an enormous improvement over the previous FK-only method of animating.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
===Scripts===
We used a number of scripts for the purpose of making the [[Using_the_Rigify_animation_rig|Rigify Oni rig]] usable, however those scripts have become obsolete with the introduction of the BlenderOni plugin. They are nonetheless archived [[/Obsolete scripts|HERE]] for legacy purposes.

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ".

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-14T16:29:56Z

Delano762: /* Animation rig with IK and FK */

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have a rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender.

This rig is intended to be used together with [[#BlenderOni|BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
===Scripts===
We used a number of scripts for the purpose of making the [[Using_the_Rigify_animation_rig|Rigify Oni rig]] usable, however those scripts have become obsolete with the introduction of the BlenderOni plugin. They are nonetheless archived [[/Obsolete scripts|HERE]] for legacy purposes.

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ".

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]

Blender

2022-05-14T16:29:28Z

Delano762: Added the BlenderOni header, made some minor changes

{{fmbox
| text = This page should contain information up to date for Blender version 3.1.
}}
Blender is a free and open-source 3D computer graphics software toolset used for 3D modeling, animating, rigging, texturing, video editing, digital drawing, etc. It is the community's current 3D software of choice for modding Oni.

==History of Blender in Oni community==
Up until 2019, the community's 3D program of choice was [[Mod Tool|XSI Mod Tool 7.5]], a free version of Autodesk Softimage from 2009. Softimage itself became discontinued in 2014, so the community was using a horribly outdated software for a long period of time. The reasons for that were two: XSI was the only software that the community could make any sense of (although very limited) and it had no problems handling Oni's assets and animations, unlike other programs.

Blender during that time, although available, was widely considered as a trivia, rather than a serious 3D software. Reasons for that were multiple, with the most known being its infamously notorious user interface used up to Blender 2.79. In case of Oni, another prime reason for not using it was that [[#Oni-specific_issues_with_Blender|importing Oni's assets to Blender was causing a number of issues]], the causes of which were unknown at the time.

However, Blender's user interface received a total overhaul in version 2.80, which was universally praised. This, along with the updates that Blender is receiving to this day, its light weight and countless tutorials on Youtube, made it effectively a serious competitor to the industry-standard 3D programs like Maya or 3DS Max.

With Blender having become significantly more user-friendly and popular, it became more and more clear that it was necessary for the community to move on from XSI to Blender. The final straw was that it became clear that using XSI was ridiculously ineffcient, due to outdated methods used to create assets and XSI being bugged.

From 2020 to 2022 a significant amount of work was done to allow modding Oni in Blender: the -blender tag was introduced to [[OniSplit]], which allowed to convert Oni assets in a way so that they can be imported to Blender, a new [[Using_the_Rigify_animation_rig|animation rig]] tailor-fit for making Oni animations was created, along with [[BlenderOni]] - a companion tool for the said rig. With all of this done, the community can now create new content for Oni in a modern, free, commonly used and open source 3D software.

==How to use Blender? Tutorials and resources==
With the abundance of tutorials for Blender on Youtube, writing down tutorials on the basics of it would be reinventing the wheel, and a worse one at that. So instead, we recommend watching some of the tutorials listed below and trying to do some simple personal projects to get familiar with Blender, such as modeling simple objects like teddy bears or tables.

General Blender basics:
* [https://www.youtube.com/watch?v=RG8qK5zPqgM Wolf's 45-Minute Crash Course for Blender Virgins] (yes, seriously - this is one of the best Blender basics tutorials out there, it's particularly good if you know your basics already and you want to find out if you've missed anything)

Modelling
* [https://www.youtube.com/watch?v=1jHUY3qoBu8 Learn Low Poly Modeling in Blender 2.83 (Imphenzia)]

Rigging
* [https://www.youtube.com/watch?v=vKgH5zXIYmM Rigify (CGDive)]

Documentation
* Blender has excellent documentation, available [https://docs.blender.org/manual/en/dev/modeling/meshes/editing/face/index.html HERE]

==Development==
[[Image:Blender_2.8_Python_Tooltips.png|thumb]]
You may want to go to the preferences and switch on '''Python Tooltips'''.

Contrary to intuition, the '''Developer Extras''' do not give you additional Python functionality per se. Instead this option enables experimental Blender features.

Related videos:
* [https://youtu.be/XqX5wh4YeRw?t=46 Python Crash Course for Blender! - Curtis Holt]
* [https://www.youtube.com/watch?v=uahfuypQQ04 Blender 2.8 Addon Development Tutorial for Beginners - Jayanam]

==Animation rig with IK and FK==
Currently we have a rig available in the form of a Blender scene available [http://mods.oni2.net/node/388 HERE]. The rig was made by Geyser and Delano762, and a tutorial on how to use it is available [[Using_the_Rigify_animation_rig|HERE.]] The rig is based off the Rigify plugin for Blender.

This rig is intended to be used together with [[#BlenderOni]], a Blender addon designed as a companion tool for it - '''the rig is extremely difficult to set up without it, to the point of being almost useless.'''

The rig has the following capabilities (which come with Rigify by default, unless otherwise noted):
* Snapping to Oni animations through bone constraints controlled by the Z location of the objects in the Pose Matching layer (added feature)
* Inverse and Forward Kinematics (IK and FK)
* Snapping between IK and FK chains
* Function to snap IK hand controller rotation to the wrist bone, integrated into rig_ui.py (added feature)
* IK joint poles for specifying limb joints (elbows and knees) should be facing
* Sliders specifying how much the neck, head and FK limbs should retain their world space rotation – that is, Neck Follow, Head Follow and FK Limb Follow
* IK foot pivoting controllers around toes and the heel
* Root bone

===Tutorial for creating animation rig===
If you want to create the above rig, and learn a bit about rigs, IK/FK, Rigify, Blender, bone layers, bone constraints, scripts, issues with Oni models and animations such as the rotation order being incompatible with Blender, see [[Creating an animation rig in Blender]].

==BlenderOni==
===Scripts===
We used a number of scripts for the purpose of making the [[Using_the_Rigify_animation_rig|Rigify Oni rig]] usable, however those scripts have become obsolete with the introduction of the BlenderOni plugin. They are nonetheless archived [[/Obsolete scripts|HERE]] for legacy purposes.

==Oni-specific issues with Blender==
===Rotation order issue between Oni and Blender===
The previous XSI process allowed us to get to work pretty quickly: you could simply export any animation from Oni as a COLLADA file using OniSplit, then import it to XSI and it would work (mostly) without any quirks. That is not the case with Blender.

If you import any Oni animation into Blender as it is, the rotations will be all wrong.

That's because Oni's rotations are stored in XYZ Euler rotation order, while Blender's XYZ is actually ZYX despite being called "XYZ".

You can prove that by simply switching the rotation order of the body parts from XYZ to ZYX, as shown below – the image on the left shows KONCOMcomb_p imported to Blender without any adjustments, with the rotation order set to Blender's default "XYZ", while the image on the right shows the same animation after switching the rotation order to ZYX.

{| class="wikitable"
|-
! KONCOMcomb_p in Blender's XYZ !! KONCOMcomb_p in ZYX
|-
| [[Image:ARB KONCOMcomb p XYZ.png|500px|frameless]]
| [[Image:ARB KONCOMcomb p ZYX.png|500px|frameless]]
|}

Because of this, geyser implemented the '''-blender''' argument in OniSplit, which solves this problem by converting Oni assets' rotation order from XYZ to Quaternions and then to ZYX, and vice versa when exporting assets from Blender to Oni. So that conversion flow looks as follows:

*From Oni to Blender:
XYZ → Quaternions → ZYX

*From Blender to Oni:
ZYX → Quaternions → XYZ

To summarize: '''Always use the -blender argument when you're exporting assets from Oni to Blender''', otherwise you can expect the problem shown in the above screenshots.

===Broken alpha transparency and textures on animated models===
'''Currently there is no option in OniSplit that would allow exporting animated models with textures.''' While you don't need textures for animating, they are very useful, particularly in case of Oni - the models are low detail to a point where you can lose sense of which direction elbows and knees are facing, if you don't have the textures on.

Because there is no option to export animated models with textures, '''the current workaround for that is to import an unanimated model with textures, then import an animated model,''' and either copy materials from the unanimated model to the animated one (the faster method), or set the materials on the animated model manually.

You will also most likely need to set shading settings on some body parts on the unanimated model to fix Alpha transparency issues (much like in XSI) - specifically connect the Alpha parameter of Base Color node to any parameter in Principled BSDF that will work, like Emission Strength (this should be set up differently as that's technically incorrect, but I don't know how at this moment).

{| class="wikitable"
|-
! Konoko upon importing to Blender !! Fixed transparency !! Copying materials !! Setting materials in Shading
|-
| [[Image:ABR Konoko broken alpha.png|200px|frameless|center]] || [[Image:ABR_Konoko_fixed_alpha.png|200px|frameless|center]] || [[Image:ABR_Copying_materials.png|200px|frameless|center]] || [[Image:ABR Konoko fixed alpha.png|200px|frameless|center]]
|-
|}

[[Category:Bi-platform modding tools]][[Category:Completed modding tools]]