OniGalore - User contributions [en]

User:Paradox-01/South Africa Syndicate HQ

2025-01-23T01:01:40Z

Vortice: Update notice w/ summary

{{update|This article contains dead or broken links.}}
Had an [[User:Paradox-01/Accessible_sniper_tower|alternate version of accessible sniper tower]].

<gallery>
Image:South_Africa_Syndicate_HQ.png|Draft 1
Image:South_Africa_Syndicate_HQ_collage.png|Draft 2 (lost)
</gallery>

===Backup===
Draft 1:
* https://assets.adobe.com/public/b7f2d20e-5e8c-439e-46ef-5db4ba5f2c5c

[[Category:Modding projects‎]]

Blender

2025-01-22T22:43:34Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: History of Modding with Blender}}
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://www.youtube.com/watch?v=XqX5wh4YeRw&t=46s 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==
===Fixing texture mapping of DAE files===
Replace all instances of <technique> with <technique sid="common">.

===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]]

Graphics

2025-01-22T22:33:32Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Occlusion -> Raycasting}}
Here are explanations of various aspects of Oni's graphical code.

==Environment mapping==
:Wikipedia: [[wp:Reflection mapping|Environment mapping]]
It's a technique to simulate reflectivity: the diffuse texture is mapped using regular texture coordinates (UVs), and there's an additional texture layer, the UVs for which are generated from the vertex normals and the orientation of the object in space (and, ideally, the orientation of the camera). While env mapping is the most advanced shader in Oni, it's about the worst implementation of env mapping there ever was (the projection is planar and the camera angle is not taken into account at all).

==Fog==
:See [[BSL:Frustum_and_fog]] on how to alter fog using [[BSL]].
:''In mid-to-late 1990s games, when processing power was not enough to render far viewing distances, clipping was employed. However, the effect could be very distracting since bits and pieces of [objects] would flicker in and out of view instantly; by applying a medium-ranged fog, the clipped polygons would fade in more realistically from the haze.'' — [[wp:Distance fog|"Distance fog"]], Wikipedia
:''For more technical information on fog and on frustum-based space (or whatever it's called), see [https://learn.microsoft.com/en-us/previous-versions/ms537113(v=vs.85)?redirectedfrom=MSDN here] and [https://learn.microsoft.com/en-us/windows/win32/direct3d9/pixel-fog?redirectedfrom=MSDN here] and [https://web.archive.org/web/20130520191527/http://cs.fit.edu/~wds/classes/graphics/PTOC/ptoc/ elsewhere].

The frustum (see below) defines a set of coordinates in which the near plane is at <tt>Z = 0</tt> and the far plane at <tt>Z = 1</tt> (<tt>X = -1</tt> and <tt>X = 1</tt> correspond to the left and right side of the frustum; the top and bottom of the frustum are planes with <tt>Y = -a</tt> and <tt>Y = a</tt>, with <tt>a</tt> the aspect ratio of the screen).

The important thing for fog is <tt>Z</tt> (the depth coordinate in frustum-based space). Every pixel of every object within the frustum is blended with a color (the fog color), depending on the amount <tt>f</tt> of fog in front of that pixel. The default fog color is 25% gray.

For <tt>f < 0</tt>, there is no fog in front of the object and the pixel retains its original color. For <tt>f > 1</tt> the object is completely fogged and the pixel has the color of the fog. For <tt>0 < f < 1</tt>, the color is interpolated linearly between the original pixel color and that of the fog.

The value of <tt>f</tt> is taken to be <tt>0</tt> on the fog's "start" plane and <tt>1</tt> on the fog's "end" plane and is interpolated/extrapolated linearly elsewhere, in the frustum-based coordinates. The natural order is: near clip plane, fog "start" plane, fog "end" plane, far clip plane.

The conversion formulas between <tt>z</tt> (units of distance from the camera) and <tt>Z</tt> (percentage of frustum depth) are:
:<tt>Z = z_f * ( z - z_n ) / [ z * ( z_f - z_n ) ]</tt>
:<tt>z = z_n * z_f / [ z_f - Z * ( z_f - z_n )]</tt>
By default, <tt>z_f</tt> is 10,000 world units and <tt>z_n</tt> is 4, so <tt>Z = 0.925</tt> corresponds roughly to <tt>z = 53.07</tt> world units (or 5.307 m, or 17.411 ft).

==Frustum==
:See [[BSL:Frustum_and_fog|Frustum and fog]] on how to alter the far clip plane and field-of-view (FOV) using [[BSL]].
:''In 3D computer graphics, the viewing frustum or view frustum is the region of space in the modeled world that may appear on the screen; it is the field of view of the notional camera. The exact shape of this region varies depending on what kind of camera lens is being simulated, but typically it is a frustum of a rectangular pyramid (hence the name). The planes that cut the frustum perpendicular to the viewing direction are called the near plane and the far plane. Objects closer to the camera than the near plane or beyond the far plane are not drawn.'' — [[wp:Viewing frustum|"Viewing frustum"]], Wikipedia

;Field of view (FOV)
:Oni defines the vertical field-of-view (FOV), i.e., the angle between the top and bottom planes of the frustum as measured at the camera's location, and its default value is 45°. On a 4:3 screen, the corresponding horizontal viewing angle is '''2 * arctan(4/3 * tan(45° / 2)) = 57.8224°'''
;Widescreen FOV
:On a 16:9 or 16:10 screen, the horizontal viewing angle for a vertical FOV of 45° is larger: '''2 * arctan(16/9 * tan(45° / 2)) = 72.73435°''' and '''2 * arctan(16/10 * tan(45° / 2)) = 67.0682°''', respectively. This causes insufficient frustum culling in some of Oni's cutscenes (intro sequences of {{C|2}}, {{C|11}}, and {{C|14}} for example). A quick way to fix this is to bring the horizontal viewing angle down to the supposed '''57.8224°''' during the cutscene: the 4:3 viewport will then effectively be trimmed vertically rather than extended sideways. On 16:9 and 16:10 screens, the corrected vertical FOV will be '''2 * arctan(3/4 * tan(45° / 2)) = 34.515877°'' and ''2 * arctan(5/6 * tan(45° / 2)) = 38.0871°''', respectively. Remember to set it back to 45° after the cutscene to fully enjoy the extended viewport. (Note that the [[AE]] contains patches for some of these cutscenes.)

==Occlusion==
A game never needs to draw all the objects in a scene at all times. Whole parts of the scene (polygons, meshes or groups of objects) can thus be "culled" (i.e. killed, not drawn).

An object (polygon, mesh) can be culled for several reasons, including the following:
*it's outside of the camera's field of view (view frustum culling)
*it's within the camera's field of view, but it's hidden by other objects (occlusion culling)

Culling speeds up the drawing process, but runtime detection of objects that need to be culled also takes time... One generally adopts a hierarchical subdivision of the scene, whereby the children (subparts) of a large object are automatically culled if their parent (the large object) is detected as hidden or out of sight.

Oni's solution is the combination of two algorithms: oct trees and ray casting.

;Oct trees
:Unlike the more common "visibility groups" placed manually by the level designer, Oni uses an automatic partition of the visible space into smaller and smaller cubes, until each "leaf" cube holds no more than a certain small number of polygons (see [[OTLF]] for details). Environment polygons (as well as characters, particles, etc) will only be drawn if they are in a leaf node of the oct tree, and if that leaf node is detected as visible. The detection of whether a leaf node is visible is done with ray casting.

;Ray-casting
:Wikipedia: [[wp:Ray casting|Ray casting]]
[[Image:Ray-casting failure.jpg|thumb|right|If you've ever thought that you briefly saw flashes of color while turning the camera, now you know why. Wherever a polygon is not rendered, the level's skybox will be visible.]]

It's an original algorithm that achieves both view frustum and occlusion culling. During each frame, 16-20 rays (depending on graphics quality) are shot from the camera into the environment, distributed randomly in the frustum. Along the path of each ray, the engine first determines the relevant leaf node of the oct tree (either by navigating the oct tree or using the information on the neighbors of the previously traversed leaf node), and then the ray is tested for collision with non-transparent environment quads intersecting that node (if the ray is stopped by a quad, then its further path is ignored). Quads thus detected with collision will be drawn. An overview of the algorithm is presented in the paper [http://oni.bungie.org/archives/brent_gdc00.html An Algorithm for Hidden Surface Complexity Reduction and Collision Detection Based On Oct Trees] by [[Credits|Brent H. Pease]] (note that figure 1 and 2 are mixed up).
:Just a side note: the ray-casting feature which handles occlusion/frustum is not to be confused with the common term "[[wp:Ray tracing (graphics)|ray-tracing]]", a CG rendering method where a ray is cast for every rendered pixel, achieving a high degree of photorealism. This method is very CPU-intensive and is typically used only for still images, short video sequences or CG movies such as Pixar's ''Cars''. Implementations of real-time ray-tracing for gaming are underway, but still need to be complemented with the standard [[wp:Scanline rendering|scanline rendering]] and [[wp:Rasterisation|rasterisation]] approaches for performance reasons.
Pease acknowledges that even ray-casting was too CPU-intensive until they lowered the number of rays being emitted and started altering their emission angles even when the camera remained still, in order to catch any polygons that the first emission of rays missed; this is why distant polygons, when suddenly revealed by the camera, sometimes are culled at first (pictured, right) and then appear a moment later: because the rays didn't hit them on the first pass. A distant face in the environment can be accidentally culled if it's only visible through a narrow slit, because the rays have a low probability of passing through the slit and hitting the objects behind it. A similar problem occurs when modders experiment with outdoor levels that have uneven ground (natural terrain): many of the ground polygons will be culled, making the map look like there are holes everywhere.

==LOD==
Oni uses the graphics quality slider in Options to help determine what level of detail (LOD) at which to render characters. Each character has up to 5 LODs, though one 3D model can be used in as many of the 5 slots as desired. The first step in determining which LOD to draw each character at is to consult [[XML:ONCC#<LODConstants>|this table]] found in the character's ONCC.

After that distance-from-camera filter is applied, Oni counts the total polygons of all characters in the scene (henceforth "TPCS"). If TPCS is not above the maximum character polys in the scene ("MCPS") which is allowed by the game's graphics quality setting, the game then experiments with raising the LOD of all characters one level at a time, stopping when it would pass MCPS. If TPCS is starting off above MCPS, it lowers all characters' LOD one level at a time until it gets below that limit.

For reference, here is the table of MCPS by graphics quality level: (1500, 2200, 3000, 3400, 4000). Note that there is no consideration at all for how many environmental polys are in the scene.

Next, iterating over each character from closest to farthest, the LOD of that character is raised by 1 as long as this won't raise TPCS over MCPS. Thus Oni seeks towards the maximum detail level that it can use for each character, prioritizing the closest ones. As a special consideration, if the closest character is below Medium LOD, it is raised to Medium regardless of MCPS, and the second-closest character is raised to Low if it was Super-Low.

Once the desired LOD is determined for a character, they will be switched to it immediately if they are not standing still (which would make the switch too noticeable). If they are moving, the game waits several frames to make sure the new LOD is continuously being requested by the above algorithms and then they are switched. The goal is to avoid a character rapidly switching back and forth between LODs.

After all the above considerations, one more: if a cutscene is playing, every character is guaranteed a minimum LOD of Low so that no one will be rendered at Super-Low detail.

[[Category:Engine docs]]

XML:TRAM

2025-01-22T22:13:16Z

Vortice: Update notice w/ summary

{{XML_File_Header | prev=TRAC | type=TRAM | next=TRAS | name=Totoro Animation}}
{{update|This article contains links to the now defunct Oni Central Forum. Sections: List of Tags near <Attack>, Editing 3D Data}}
{{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:Finite-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 {{SectionLink||Weights}} 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:Moonwalk (dance)|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, but can still take damage from particles and falls.
:BlockHigh
::While playing this animation, the player can block high or undefined-height attacks within some arc in front of him. The height of an attack is found under the <Attack> section. 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-height attacks.
:Attack
::Unused by the engine.
:DropWeapon
::If the player is armed, he drops his weapon when this animation plays.
:InAir
::Unused by the engine.
:Atomic
::Unused by the engine. Only the Start and End frames of the Atomic field below matter.
:NoTurn
:::Player cannot turn while performing this animation.
:AttackForward
::Unused by the engine.
: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
::Oni expects this flag on all throw source animations.
:::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> from [[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
::Unused by the engine. It appears this flag was used during the authoring process 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 TRAMs with this flag 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
::Unused by the engine.
:DisableShield
::If the player has an active [[supershield]], this disables it (the flag is placed on four Mutant Muro attacks: his two supers, the claw-stuck-into-ground move and the sliding "[[wikt:kancho|kancho]]" maneuver; it is also hardcoded to be removed when the Zeus Thunderbolt attack is used).
:NoAIPickup
::AIs are not permitted to pick up items with this animation.
|-
| <Atomic>
| parent tag
| Animation cannot be interrupted by player between the Start and End frames.
|-
| <Start>
| int16
|
|-
| <End>
| int16
|
|-
| <Invulnerable>
| parent tag
| Character will not take melee damage and cannot be thrown between 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 on the player character, 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 at the start of the animation:
*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; this will lift the target's collision sphere off the ground as if they jumped. However 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 or else the equivalent TRAM will play when the throw takes place outside of this TRAM's range and within that TRAM's range.
|-
|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 still receives half of the normal damage.
|-
| <Knockback>
| float
| Target gets knocked back by this amount if attack is successful.
|-
| <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. If ≥ 20, Oni automatically upgrades the character to a stagger animation.
|-
| <StunLength>
| int16
| Number of frames that the target should remain in his blocking animation state when he blocks the attack. If ≥ 15, Oni automatically upgrades the character to a block stun.
|-
| <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 under {{SectionLink||Using OniSplit to calculate extents}}.

'''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 for vanilla Oni}}
{| 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}}

;Running disarms
Oni offers support for running disarms (originally noticed [[OBD:BINA/OBJC/MELE/MoveList/Throw|HERE]]), which was taken advantage of by Delano's mod [http://mods.oni2.net/node/353 54000 New Combat Moves for Konoko].

;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.

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, with links to videos of them where applicable. 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.
* [https://www.youtube.com/watch?v=dszw2vmlmzw 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.
* [https://www.youtube.com/watch?v=CRuZq_uYOQk 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 (see above link): 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}}

Creating an animation rig in Blender

2025-01-22T20:11:04Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Summary -> SoftImage XSI, Things to know -> Brief overview on TRAMs}}
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://www.youtube.com/watch?v=f2pTkW-1JkE&t=343s 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.app/ '''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 preceding 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/Obsolete scripts#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/Obsolete scripts#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/Obsolete scripts#Visual transformer script|HERE]] to bake the rig keyframes into the character model.
# Using the ObjectConstraintEnabler script available [[Blender/Obsolete scripts#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|The expected result by the end of this section.]]

# 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 frame rate 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, [[Blender#Lack of textures on animated models|apply textures to the animated models]] and [[Blender#Alpha transparency issue|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|The expected result by the end of this section.]]

# <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 Orthographic 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 the ''spine.003'' bone to ''spines.super_head''.
# Enable the ''Connect chain'' checkbox on the ''spine.003'' bone.
# Disable the ''Widget'' checkbox on the ''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 the 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/Obsolete scripts#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 positions 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 constraints 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/Obsolete scripts#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]]

Introduction to modding

2025-01-22T19:35:32Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Modding Resources -> Tutorial Lair, Tutorial Character Classes}}
This page provides an introduction to modding that does not assume that you have prior modding experience or knowledge of the Oni engine. Links to more technical parts of the wiki are interspersed below or can be accessed directly from the wiki's Main Page.
{{TOClimit}}

==What is modding?==
[[Image:No easy button.png|150px|right]]
Modifying, or "modding", a game is generally easier than creating one, because you might only be changing some of the game's existing elements, or creating a limited amount of new data. Nevertheless, modding can be an intimidating field to get into. Our community does not have the polished modding tools of the big engines like Unreal (but we're getting better). You should have a [[wikt:DIY|DIY]] personality and a high tolerance for technical details. We do not yet have any modding solutions with a big red button that says "easy".

Modding your first game is always the hardest, but after that you can more easily pick up new ones. If you take things one step at a time, you can learn a lot from Oni about how to make games in general; in fact, many game developers started out as modders. Additionally, there are lots of different ways for someone to mod; whether your interest is in coding, art, sound, 3D modeling, or general game design, there's something for you to do, and collaborating with others to divide the work according to your abilities can lead to a memorable, rewarding creative experience.

* Go to the {{OMD}} to see what kinds of mods are available, or;
* Install the [[Anniversary Edition]] to try out the mods, or;
* Continue reading to get an overview of the game engine.

==What engine does Oni run on?==
Oni runs on a custom engine that could be built for Windows, the Macintosh and the PlayStation 2 (console games are not easily modded, so we don't work with the PS2 version of Oni). The engine consists of various subsystems, some of which have colorful animé-related names like [[wp:Akira|Akira]] (environment), [[wp:Motoko Kusanagi|Motoko]] (graphics) and [[wp:My Neighbor Totoro|Totoro]] (animation).

Unfortunately, the game was rushed to completion during a change of ownership, and it was not possible for the developers to release any tools or information to aid the fans in modding. Thus, fans had to explore the wild jungle of the raw game data and create modding tools through reverse-engineering. It took over seven years to unlock most of the game's secrets, but we can now mod almost all types of data effectively, allowing us to create entirely new levels and characters.

Altogether, we have identified over 100 types of resources (often called "file types" on this wiki, and "tags" in many other game modding communities) in the game data, however we only directly edit about half of these. It may sound intimidating at first, but depending on the kind of modding you want to do, you might be able to start working with only a little knowledge of the engine.

* Go to [[Oni]] for the full story on Oni's development, or;
* Go to [[History of Oni modding]] to read about the community's accomplishments up until now, or;
* Continue reading to learn about the game data files.

==How is the game data structured?==
A game can be compared to a theater play: in both cases, you have stages, scripts, actors, and music. A level is built so that when the player performs certain actions or reaches certain locations on the '''stage''', further events are set in motion according to the '''script'''. The player interacts with [[wp:Artificial intelligence in video games|AI]] '''actors''' along the way. '''Music''' will often play dynamically behind all this, changing along with the flow of events.

In Oni's case, the stages, actors and music (and other sounds) are all packed together into files inside GameDataFolder/ that end in ".dat", ".raw", and, on Macs, ".sep". The level0_Final files provide resources for all levels, and when you load a Chapter, an additional set of data files provide the level-specific resources for that Chapter (e.g. level12_Final for Chapter 10). The scripts are stored in separate plain-text files ending in ".bsl" inside GameDataFolder/IGMD/. The player's progress is stored in persist.dat next to the Oni application.

* Go to [[Oni (folder)]] for information on each file, or;
* Go to [[Game data terminology]] to learn the precise terms for Oni's data, or;
* Continue reading to learn the general process of modding.

==What is the workflow for modding?==
The general order of events in creating a mod is (1) unpacking the resources you wish to edit, (2) editing them, and (3) re-packing them as Oni level data. You can rely on the Anniversary Edition Installer to re-pack your data; you simply create the mod package in the format that the AEI requires. If you are only creating a script mod, then you don't need to unpack any data, but you'll still need to know how to place your script(s) in a mod package.

===Data unpacking===
The game data cannot be edited easily until our tools convert it into something more modder-friendly. You will usually start by using OniSplit to break level data files (those .dat/.raw(/.sep) files) into their component resources, which are saved as .oni files. Then you will need to convert those resources into something editable. The editable format you arrive at will depend on the kind of data you're editing. It might be plain text, XML, PNG, Collada, WAV, etc. The editors which you'll use on this data will be third-party programs suited for each file format.

===Third-party tools===
If you are scripting, then you might need nothing more than a text editor. For editing textures, you might only need a free bitmap editor. For creating levels or characters, you'll need a full 3D modeling package. Since Oni doesn't have modern 3D graphics, you won't need to know as much about modeling/texturing as you would with a modern game, and there are free modelers available. Our recommendations for tools will be found under the subsections of "Modding resources" below.

===Community tools===
Besides OniSplit, two of the key fan-made tools are Vago and XmlTools. Vago is a GUI for OniSplit which is much more user-friendly than using OniSplit on the command line. [[XmlTools]] is a technical tool that few modders need to use, but it allows the creation of patches (partial changes to a single resource which can stack on top of each other). Both tools can be installed from within the AE Installer. Once installed, they are found in AE/Tools/ alongside OniSplit.

===Mod creation===
To see how mods normally look and how they're distributed and installed, you should download the [[Anniversary Edition]] and install some mods. You can then look at the packages that have been downloaded to AE/AEInstaller/packages/.

* Go to [[OniSplit]]'s page to learn how to unpack and reassemble the game data, or;
* Go to [[Vago]]'s page to learn how to use this OniSplit GUI, or;
* Go to [[Making a mod package]] to learn how to assemble a mod, or;
* Continue reading to learn about the types of modding you can perform.

==Which resources should I be modding?==
Oni assembles its game world from the scripts in the IGMD folder, the game data in the .dat/.raw(/.sep) files in GameDataFolder, and [[persist.dat]]. It's easy to read the BSL scripts since they're plain-text, but how do you find the resource in the game data that you want to edit? Look under "Modding resources" below for a link to the XML database, which explains the function and location of each resource type.

===Editing scripts===
The easiest kind of modding is scripting. Scripts are written in a unique language called BSL and stored as plain-text files with the suffix .bsl in sub-folders inside GameDataFolder/IGMD/. Scripts take a lifeless level and spawn characters in it, give it a logical flow of events, drive the cutscenes, make the AIs perform certain roles, and alter the level's appearance.

Scripting is the easiest way to mod because you can modify BSL files using a text editor. It's quick and easy to see the results of your work (just reload the level), and you have lots of accessible examples to learn from. That being said, scripts sometimes reference game resources in technical ways, so you will have to learn how certain data types work in order to script effectively.

* Go to the [[BSL]] namespace to start learning about scripting, or;
* Continue reading to learn what's involved with editing binary resources.

===Modding resources===
Broadly speaking, Oni's resources can be broken down as: '''environments''' (architecture, triggers, furniture), '''characters''' (class data, instance lists, 3D models), '''weapons''' (ditto), '''text''' (diary pages, objectives, subtitles), and '''sound''' (music, voice-overs, and sound effects). However, new levels do not require all this data to be made from scratch. You might decide to re-use a level or some of its resources, or make a new level populated with existing characters, etc.

* Go to the [[XML]] namespace to get a simple introduction to the types of game data and learn the (relatively) user-friendly XML modding technique, or;
* Go to the [[OBD]] namespace to learn more technical details about the game data, or;
* Continue reading to start down the path to modding specific kinds of resources.

====Environments====
Levels are usually built in [[SketchUp tutorials and tips|SketchUp]]. The open-source tool [[Blender]] can be used for levels, objects, characters and animations. Formerly we preferred to do that work in [[Mod Tool]], but the community's support for Blender has continued to improve and it is now our modeler of choice.

* Tutorial: [http://oni.bungie.org/forum/viewtopic.php?id=2087 Creating the Lair]
* Tutorial: [[Authoring custom camera animations]]

====Textures====
Modders have their own preferred bitmap editors for changing/creating textures. On one end of the scale are expensive programs such as Photoshop, and on the other end are free editors like [https://www.gimp.org/ Gimp] and [https://www.getpaint.net/ Paint.NET].

Textures always have dimensions of "power of 2": typically 32, 64, 128 or 256 pixels on a side. Mac Oni supports a maximum of 1024x1024 textures. Windows Oni supports textures up to 512x512.

These textures can be static, animated, transparent or have a reflection map (usually used for armor). Splashscreens (chapter start screens), win-level and lose-level screens are actually composite images made up of smaller textures due to Oni's limitation in texture size.

* Tutorial: [[Modifying textures]]

====Characters====
[[Image:Female stun.jpg|right|300px]]
Characters in Oni are built with a 19-part skeleton. This skeleton is the same for all humanoid characters and simply tells Oni how the individual parts with their own geometry and textures are assembled. You cannot really compare this with the modern game industry's use of the term "skeleton".

A character's attributes are defined by their character class file which links also to the animation list that defines their moveset. The high modularity of character data allows Oni to share many resources between characters (especially animation collections and particles).

* Tutorial: [http://oni.bungie.org/forum/viewtopic.php?id=2423 Adding character classes]
* Tutorial: [[Importing character models]]
* Tutorial: [[OBD talk:TRAM|Tweaking an individual animation]]
* Tutorial: [[Adding spawnable characters|Adding spawnable characters to a level]]

====Weapons====
* Tutorial: [[Importing weapon models]]

====Text====
The text-based resource types are fairly easy to edit as long as you don't get confused by the IDs which they use to link to each other. The main textual resources are the pages you can view in the [[Data Comlink]] and the consoles you read in-game. The textual resource types are listed here: [[OBD:File types/Interface#List]].

====Sound and music====
Instructions on importing sounds, and links to conversion tools, can be found [[XML:SNDD|HERE]].

==Need some inspiration?==
To get ideas, play some existing mods (which you can install with the [[AE]]), or look at the pages below.
* [[Modding brainstorms]]
* [[Review criticisms]]
* [[Animation ideas]]

[[Category:Modding tutorials]]

Mod Tool

2025-01-22T19:24:00Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Selected Wisdom}}
Autodesk's Mod Tool used to be the main choice for modders when working on level and character models (at least in Windows, since it's Windows-only). It was a free and accessible program, but has long since been discontinued. Nowadays, modders are encouraged to use [[Blender]] instead.
{| class="wikitable" style="float:right;"
|width="200px"|
;sub pages
: [[Mod_Tool/Scripting]]
: [[Mod_Tool/Rigging]]
: [[Mod_Tool/OniTools_addon]]
: [[Mod_Tool/Oni_level_rebuilder]]
|}

==Installation==
Full name: "Autodesk Softimage Mod Tool". Usually we just call it "Mod Tool" or "XSI", the old name of the program.

'''Download'''
* '''Get it from [https://www.moddb.com/downloads/autodesk-softimage-mod-tool-75 Mod DB].'''
* It's no longer possible to download Softimage from Autodesk because the [https://www.autodesk.com/products/softimage/overview software was discontinued] by Autodesk in favor of their major software packages Maya and 3ds Max.

'''Newer Windows installations usually require .NET 2.0 to be installed before the XSI installer can fully run.'''
: Downloading and installing .Net 2.0 manually from the internet might not work.
: '''Therefore use the Windows search and look for "features".''' (Enable/disable Windows features.)
: From the Windows feature page install '''".NET framework 3.5 (includes .NET 2.0 and 3.0)"'''.

There are various ways to extend Mod Tool's range of functions: scripts (.vbs, .js), toolbars (.xsitb) and addons (.xsiaddon). They can be created on one's own and also shared with other users.

===Extensions===
'''links'''
* [https://www.si-community.com/community/viewtopic.php?f=35&t=796 "Roadkill" UV Tool]
* [http://web.archive.org/web/20121001104022/http://www.xsidatabase.com:80/content/drag_and_drop_obj_files_jscript drag and drop support for OBJ files]
* [https://www.si-community.com/community/viewtopic.php?f=35&t=797 OBJ exporter]
* [http://mods.oni2.net/node/210 OBJ + OFGA exporter] for Oni
** might need the regular OBJ exporter to be installed first
* [http://mods.oni2.net/node/210 adjusting existing fw throws] [https://www.youtube.com/watch?v=vDTPYfvMf4M (instructions)]

'''how to bind scripts to buttons (embedded code or .vbs / .js)'''
* You can enable/disable the Main Shelf over "View" > "Optional Panels" > "Main Shelf". Then click the "Custom" tab.
* A) Right-click the free gray space, click on "Customize Toolbar...". Select "Toolbar Widgets" > "Script Button".
:* Enter your code and make sure you selected the correct Scripting Language. Click okay when you are done.
* B) You can also drag'n'drop your script file directly onto the free gray space.
:* A new window pops up, check the settings and click okay when done.
* Right-click the Main Shelf and use the "Save" option. ("Save As" let you save the Main Shelf as toolbar file.)

'''how to install toolbars (.xsitb)'''
* creation: goto "View" > "New custom toolbar"
:* Now you can add buttons like in Main Shelf. Remember to save your changes. (Right-click, "Save As".)
* '''installation:''' Drag'n'drop the xsitb file onto the viewport (it's simply the window where you can see 3D objects).
* access: goto "View" > "Toolbars"
* deletion: goto "View" > "Manage..." Check a toolbar and click Delete button.
:* The file will remain with a new file suffix ".bak" You can restore this backup if you remove the ".bak" from the name.

'''how to install add-ons (.xsiaddon)'''
* A) drag'n'drop the file into the so-called viewport (it's simply the window where you can see 3D objects), then restart Mod Tool
* B) if drag and drop doesn't work, goto "File" > "Add-On" > "Install"
:* Then click on the "..." button to search for the file. When you found it, click the "Install" button.

'''building add-ons (<nowiki>http://softimage.wiki.softimage.com/sdkdocs/cus_addons_WalkthroughBuildinganAddon.htm</nowiki>, dead link)'''
* Building an add-on file needs more effort than the other 'extensions' but for the end user it's best because it can hold all other files: toolbars, plugins (scripts), etc.
** The user can install a newer version of the addon by repeating the installation with the new file: it's unnecessary to remove the old version.
* File > Add-On > Package... doesn't work with ModTool "Add-Ons cannot be created with Softimage Demo Version."
* Images and any other files can be put into any folder of the add-on.
** Let's say you have an addon called "my_stuff", a subfolder "images" and an image called "test.png". The image can be accessed via:
:: '''''XSIUtils.ResolvePath("$XSI_USERHOME/") & "Addons\'''my_stuff\images\test.png"''
* The problem with embedded code: commands like ''CreatePrim'' can call an property page (PPG).
** Those popups can be disabled. Search for "disabling PPG popups" on this page.
* '''Putting scripts simply into folders doesn't work, they must be "plugins", the file extension can be the same e.g. "vbs"'''.
** A script function can run on another computer if it is found as command, and plugin register new commands.
** E.g. you can use those commands in your toolbar's script buttons.
* Example of turning a function into a command:

'''function with arguments as it is'''
' this function can only be used inside the script where it was defined

function simple_math (a, b, operator)
if operator = "+" then
simple_math = a + b
elseif operator = "-" then
simple_math = a - b
elseif operator = "/" then
simple_math = a / b
elseif operator = "x" then
simple_math = a * b
else
logmessage "The used operator is not allowed. Choose one of the following:" & vbCrlf & "+ - / x"
end if
end function

' example of usage
result = simple_math(5, 3, "+")
logmessage result

''' the same function as command'''
' the command simple_math can now be used in any script

function XSILoadPlugin( in_reg )
in_reg.Author = "your_name"
in_reg.Name = "simple_mathPlugin"
in_reg.Email = ""
in_reg.URL = ""
in_reg.Major = 1
in_reg.Minor = 0

in_reg.RegisterCommand "simple_math","simple_math"
'RegistrationInsertionPoint - do not remove this line

XSILoadPlugin = true
end function

function XSIUnloadPlugin( in_reg )
dim strPluginName
strPluginName = in_reg.Name
Application.LogMessage strPluginName & " has been unloaded.",siVerbose
XSIUnloadPlugin = true
end function

function simple_math_Init( in_ctxt )
dim oCmd
set oCmd = in_ctxt.Source
oCmd.Description = ""
oCmd.ReturnValue = true

dim oArgs
set oArgs = oCmd.Arguments
oArgs.Add "a",siArgumentInput,"0"
oArgs.Add "b",siArgumentInput,"0"
oArgs.Add "operator",siArgumentInput,"0"
simple_math_Init = true
end function

function simple_math_Execute( a, b, operator )
' convert to double
a = cdbl(a)
b = cdbl(b)

if operator = "+" then
simple_math_Execute = a + b
elseif operator = "-" then
simple_math_Execute = a - b
elseif operator = "/" then
simple_math_Execute = a / b
elseif operator = "x" then
simple_math_Execute = a * b
else
logmessage "The used operator is not allowed. Choose one of the following:" & vbCrlf & "+ - / x"
end if
end function

==Selected wisdom==
We've also a [http://oni.bungie.org/forum/viewtopic.php?id=1229 tutorial thread on OCF.]

Hotkey list can be found [http://www.keyxl.com/aaacbe0/415/SoftImage-XSI-keyboard-shortcuts.htm here].

===Visibility===
* show/hide grid: [G]
* display polygon normals: click the eye symbol, select "Polygon Normals" (now you know the polygons ''up and down'')
* display triangle count: click the eye symbole, select "Selection Info"

===Camera navigation===
* reset view: [R]
* zoom camera: [Scrolling]
* move camera: [S] + [LClick] + [MoveMouse]
* rotate camera: [S] + [RClick] + [MoveMouse]
* pan camera: [S] + [MClick] + [MoveMouse]
* move camera mode: [Z]
* rotate camera mode: [O]
* pan camera mode: [P]
* use camera mode move/rotate/pan with: [LClick] + [MoveMouse]

===Mesh===
* scale mode: [X]
* rotate mode: [C]
* translate mode [V]
* manipulate tool: [B] (a gray box appears with gray balls at the corners)
** drag inside the object to move it
** drag an edge to rotate it
** drag a ball to scale it
* object selection mode: [Space]
* extracting a polygon from an object: select polygon, right-click, "Extract Polygons (Delete)"
* copying an polygon from an object: select polygon, right-click, "Extract Polygons (Keep)"
* '''merging two objects''': select object A, then goto Model > Modify > Poly. Mesh > Boolean > Union, select object B
: (this makes a copy of object B and attaches it to A, the '''merged objects (A) must be freezed''' before the original object B can be removed)
* filling a hole: select all edges surrounding the hole and choose one of the following methods
** A) goto Model > Modify > Poly. Mesh > Weld Boundary Points/Edges
** B) goto Model > Modify > Poly. Mesh > Bridge Boundary Points/Edges (if blue lines appear try to disable the checkbox "Angle > 90")
* merging two objects at blue lines: merge the objects at first, then proceed with the point above "filling a hole"
* '''merging two objects with UVs''': Create > Poly. Mesh > [https://web.archive.org/web/20160225163131/http://cryrid.com/images/temp/XSI/merge_materials.jpg Merge]
** extracted Oni characters have their materials and hence textures directly grouped under the mesh (see Explorer)
** when adding (merging) a new part to the existing mesh, the materials/textures will be grouped under (Explorer again) mesh > Polygon Mesh > Clusters > ...
** Samer reported that saving the file via fbx solves a problem when trying to convert TRBS
** one would need to move the content by hand in the explorer to bypass the fbx
* hiding some objects/polygons: select object/polygon and hit [H], use [Control] + [H] to unhide all
* mirroring an object: select object, Modify > Poly. Mesh > Symmetrize Polygons
* working with symmetry mode (look below at "Low poly modeling" section for other possibilities with symmetry)
** select object, Property > Symmetry Map (YZ/XZ/XY) (press [W] to preview symmetry plane)
** click on Sym buttom (in Transform area) to enable/disable symmetry mode
** changing the Symmetry plane: Explorer [8] > unfold object > Polygon Mesh > Cluster > delete SymmetryMapCls; then add a new symmetry plane

====Low poly modeling====
* select edge loop: while being in selection mode Edge, press [Alt] + [MClick]
* modify point/edge/polygon: [M]
** press left mouse button and hold it, move mouse to translate point/edge/polygon freely
:: if axes symbol is active you can left-click a component and the translate axes pop up
:: if magnet symbol is active the translation will be limited by the surrounded components
:: if point symbol is active then only points can be selected, moving one point onto another will weld them

* By the way, combining edge loop with component selection [M] and active magnet gives an interesting effect: a line of edges will mimic the shape of their neighbor edges as closer the selected edges comes to the neighbors.

* '''getting images into Mod Tool that serve as modeling reference:'''
** click where you can set the view mode (e.g. to "Wireframe"), select '''"Rotoscope"'''
** in the appearing window at "Image Placement" choose "Fixed" so that the image will be zoomed when you zoom on the object
** choose an image by clicking the button "New"

'''symmetry in modeling:'''

You could make A) only one half of an object or B) selected polygons and then mirror and merge the parts.
* A) select object, [Alt] + [RClick] object, Symmetrize Polygons
* B) select polygons, [RClick] one of them, Symmetrize Polygons

Or you start with a half object and create a mirrored clone. You can then work on the original mesh. (In Schematics the cloned mesh will have a red "Cl" and a trapezoid shape as symbol.)
* select object then goto Edit > Duplicate/Instantiate > Clone Single
* scale X or one of the other axes to -1
* make any modification on the original mesh, the clone will adept them
* eventually merge cloned and original mesh, freeze them to make changes final

====Exchange meshes in hierarchies====
Let's say you loaded an Oni character with his 19 body parts into the scene, something is wrong and you want to fix it.

To destroy the hierarchy you must be sure the model is not animated. If there are keyframes the model will be one big mess after breaking the hierarchical links.

So, save the model with the settings "Selection Only [X]" and "Animation [ ]". Then reload the model.

Next, disable the red "Auto" button under "Animation" (if enabled). Keyframes affects also the creation of hierarchies, that's why we don't want new keyframes.

Now you can safely exchange, move and rotate meshes and their centers, and eventually rebuild the hierarchy.

===Material and texture===
[[Image:apply_new_main_texture_in_Mod_Tool.png|thumb|200px|right|how to apply a new main texture]]
[[Image:apply_new_polygon_cluster_texture_in_Mod_Tool.png|thumb|200px|right|how to apply a new polygon cluster texture]]
* objects use the scene material by default, objects need their own material if they should have individual textures
* selecting a material and surface: Model > Material > Phong (simply close the windows that pops up)
* connecting the texture with the material:
** [7] to open Render Tree
** in first column: "Texture"
** in second column: drag'n'drop "Image" into the free space
** click and hold the red point of "Image", then move it to "Phong" and release the mouse click
** choose "diffuse" as illumination mode (for instance "ambient" won't work - the texture would be visible in Mod Tool but Onisplit can't use it)
* now "Image" can be double-clicked (the Texture Editor will pop up), in the section "Image" click on "New" to choose an image
* to change textures '''don't drag and drop textures directly one meshes''', this creates textures layers which are ignored by OniSplit

===Projection and UV===
'''getting started'''
* in section "Texture Projection" click on "New", choose a projection similar to the mesh shape (planar / cylindrical / cubic / spherical)
* select the object
* Texture editor: [Alt]+[7] (open it while being in selection mode "Object" or "Polygon", otherwise the UVs aren't shown)

'''modify single/all UVs'''
* rotate 90°: [R]
* rotate: [C]
* scale: [X]
* scale height only: [X], then [Shift] + [MClick] + [MoveMouse]
* scale length only: [X], then [Shift] + [RClick] + [MoveMouse]
* move: [V]
* tearing single UV parts: [Control] + [T], then move [V]
* heal (re-connect) selected UV parts: click on the plus symbol (the parts should be very near to each other, best if the points are on same spot)
* snap function for move tool: Snap > Enable Snapping; check "Points" (if not already active)
* relax (smooth warped UVs): [Control] + [R] (usually pressing several times that combination)
* a new projection can also be applied to currently selected UV parts
* freeze object to ''bake'' projections (green lines in the 3D view will disappear)
* getting a picture of the UV: apply first a black texture then enter the Texture Editor [Alt] + [7], Edit > Stamp UV Mesh [Shift] + [S], save the texture

Things to test:
* https://vimeo.com/67783125

===Rendering===
Rendering doesn't work well on my PCs.--[[User:Paradox-01|paradox-01]] ([[User talk:Paradox-01|talk]]) 01:09, 9 March 2016 (CET)

Especially PNG, it works one time. But as soon as I import another dae the next render will fail.

So, for creating a object library we might use blender. Nice thing is, it can also render in the background when called from CMD. This means you could keep working in XSI and render images in blender at the same time.

example of a batch file:
cd C:\Program Files\Blender Foundation\Blender
blender -b --python C:\Users\Paradox-01\Desktop\blender-out\pythonScript.py

example of a render script:
import bpy

# delete blender default cube object
bpy.ops.object.mode_set(mode='OBJECT')
bpy.ops.object.select_by_type(type='MESH')
bpy.ops.object.delete(use_global=False)

# load new object
bpy.ops.wm.collada_import(filepath = "C:/Oni/r.dae")

# render settings
bpy.data.scenes['Scene'].render.resolution_x = 900
bpy.data.scenes['Scene'].render.resolution_y = 900
# default resolution percentage seems to be 50
bpy.data.scenes['Scene'].render.resolution_percentage = 100
bpy.data.scenes['Scene'].render.use_antialiasing = True
# 5 | 8 | 11 | 16
bpy.data.scenes['Scene'].render.antialiasing_samples = "8"

#TGA IRIS JPEG MOVIE IRIZ RAWTGA
#AVIRAW AVIJPEG PNG BMP FRAMESERVER
#no gif ? could be created by more code, maybe merging single frames of jpgs
bpy.data.scenes['Scene'].render.image_settings.file_format = 'JPEG'
bpy.data.scenes['Scene'].render.image_settings.quality = 100

# file suffix is overwritten by file_formate
#bpy.data.scenes['Scene'].render.filepath = 'C:/Oni/renders/test.jpg'
bpy.data.scenes['Scene'].render.filepath = 'C:/Oni/renders/test'

# start render
bpy.ops.render.render( write_still=True )

===Animating===
[[Image:Scale_animations_in_Mod_Tool_Animation_Editor_DopeSheet.png|thumb|200px|right|an animation that got scaled down from 116 to 58 frames]]

* preparing ModTool to save animations Oni can use: File > Preferences... > Preferences > Tools > Output Format
** Frame Step: 1
** Frame Format: Custom framerate
** '''Frame Rate: 60'''
* for real-time playback click on "Playback" option button and then "Real-Time Playback"
* opening the Animation Editor : [0]
* opening the DopeSheet: from any other Animation Editor, Editor > DopeSheet
* '''making an animation shorter or longer:''' in DopeSheet click Region button (arrow with rectangle), click and hold to select keyframes, at selection edge a) [shift] plus left-click and move mouse or b) middle-click and move mouse

====Issues when saving and sharing animation files (*.dae, *.exp)====
That what you currently see in Mod Tool and that what you get when saving data can be different.

1) *.dae files might save data differently than expected.

''Rotation flips'' might appear.

2) *.exp and *.dae save data differently.

*.exp files store the frames as they are.

*.dae file store their actions (rotations/translation/...) in seconds and eventually depend on what framerate a Modder uses.

'''Following scenario: a modder wants to share an animation as *.exp and another modder wants to use that animation.'''

Modder A uses 30 fps in his settings and exports an *.exp that is 58 frame long.

Modder B uses 60 fps in his setting and imports the *.exp, to his surprise the animation is 116 frames long. What now?

If Modder B saves the *.exp under a new name would not help, the frames will be still the same.

Instead Modder B could scale the animation. The way to do so is described in the [[#Animating|Animating]] section, "making an animation shorter or longer".

Modder B scales the animation and saves it as dae.

Now he wants to see if it worked. He opens a new scene [Strg]+[N] and loads the dae.

'''Summary of issue-holding aspects'''

* '''Frames Per Second (FPS)'''
When you share *.dae files with other Modders be sure that the output formate is 60 fps. Different framerates among modders can cause confusion.

Dae file store their actions (rotation/translation/...) in seconds.

An example:

<float_array count="10" id="pelvis_rotation_x_ANGLE-anim-input-array">
0.000000 0.166833 0.333667 0.500500 0.600600 0.934267 1.267933 1.601600 1.768433 1.935267
</float_array>

action at [s] * framerate [f/s] = frame [f]

In this example the last rotation occurs at 1.935267s.

: Modder A uses 30 fps, his last frame is 58.
: Modder B uses 60 fps, his last frame is 116.

* '''Euler rotations'''

you will get [[wikipedia:Bézier_curve|BEZIER]] (cubic) interpolation instead of LINEAR if you use
: "Convert Quarternion Rotation to Euler"
: "Spline Interpolation" in the animation (fcurve) editor

Those smooth the rotations.

[...]

* '''Quaternion rotations'''

Don't use this.

[...]

* '''Make Rotation Keys Continuous'''

[...]

====Animation mixer====
This could help with creating cutscenes and complex animations (e.g. run cycles for FILM files).

Open the animation mixer with [Alt]+[0].

Further information over [http://web.archive.org/web/20170103065301/http://softimage.wiki.softimage.com/xsidocs/nla_mixer.htm#Rdw10200 HERE.]

Here are a few videos:
* '''https://www.youtube.com/watch?v=-xC31Q7zpM0'''
* https://www.youtube.com/watch?v=njLrAIpDOFU
* https://www.youtube.com/watch?v=PRDZaEo5CGo

=====Sounds=====
Within the animation mixer also sounds can be added.

Further information over [http://web.archive.org/web/20170102120711/http://softimage.wiki.softimage.com/xsidocs/audio_LoadingAudioFilesintheAnimationMixer.htm#Rdy36984 HERE.]

This could be used to synchronize sounds effect with physical actions in the scene.

===Scripting===
* open the Script Editor: [Alt] + [4]
* run the current code in the Script Editor window: [F5]
* clear the log: Edit > Clear History Log
* Actions from button embedded code will be logged.
* Actions from code files that are linked in a button won't be logged. (This results in a performance boost.)
* Logged stuff will be rewritten if you change the script language. (File > Preferences...)
* You can also change the language by right-click the white script box and click on "Set to JScript" or "Set to VBScript".
* Python can be added as script language if you install it on your PC.
* Right-clicking the white script box gives you also access to a few code piece, e.g. "Syntax Help" > "If..Else" or "Catch Error".
* Mark code you want to disable ("Comment Out") or enable ("Comment Remove").
* You can save your code to a file via "File" > "Save As..." or "Save Selection"

'''Links'''
* [http://web.archive.org/web/20160803061035/http://softimage.wiki.softimage.com/index.php?title=Scripting_Tips_and_Tricks_%28XSISDK%29 xsi wiki page about scripting]
* '''[http://web.archive.org/web/20170616035120/http://softimage.wiki.softimage.com/sdkdocs/scriptsdb/scriptsdb/scrdb_vbscript.htm many vbscript examples]'''
* '''[https://ss64.com/vb/ vbs commands]'''
* [https://web.archive.org/web/20070510173452/https://www.activexperts.com/activmonitor/windowsmanagement/adminscripts/filesfolders/files/ objFSO/objWSHShell: Scripts to manage Files] (replace "Wscript.Echo" with "logmessage")
* [https://web.archive.org/web/20150504221146/http://activexperts.com/activmonitor/windowsmanagement/adminscripts/other/textfiles/ objFSO/objWSHShell: Scripts to manage Text Files]
* [http://web.archive.org/web/20080905102848/http://www.kxcad.net/softimage_xsi/Softimage_XSI_Documentation/script_basics_IncludingExternalScripts.htm using external scripts]
* [https://download.autodesk.com/global/docs/softimage2013/en_us/sdkguide/index.html?url=si_om/XSIUIToolkit.html,topicNumber=si_om_XSIUIToolkit_html progress bar and open file dialog]


'''Notes about polygon extraction'''
* a grid of 9 polygons (ID 0 to 8)
* you extract the middle polygon (ID 4)
* grid's polygon of ID 8 will change to ID 4
* if you now extract 5th, the 7th gets the ID
* now the ID order is: 0, 1, 2, 3, 6, 5, 4
* this means that an automatic extraction of several polygons requires two changes in the code
* 1) the ID array of selected polygons must be sorted
* 2) the extraction must start with the last ID to avoid ID shift during the process (see code pieces)

'''Some basics of VBScript'''
* In VBS you declare variables only as a variant e.g. "dim PolygonCount". Mod Tool decides what type it becomes when it uses the variable the first time.
* You can put "option explicit" at the start of your script. Then you will be forced to declare all variables with "dim". That looks quite unnecessary but help to find mistakes for example if you mistyped a variable somewhere in a long script.

* The commands are not case-sensitive, e.g. you can write "LogMessage" or "logmessage".
* Vbs functions can be found [https://web.archive.org/web/20150707131602/https://www.w3schools.com/vbscript/vbscript_ref_functions.asp HERE.]

' while it is possible to use + in strings,
' you should actually use & only for strings
' and + only for numbers

logmessage "How about ... " + "a riddle?"
logmessage "Where can you find following phrase in Oni? " & "The day is mine !!"
logmessage "Did you know that Bungie likes to hide sevens? The digits of the year 2032 add up to " & cstr(2 + 0 + 3 + 2) & "."

' INFO : How about ... a riddle?
' INFO : Where can you find following phrase in Oni? The day is mine !!
' INFO : Did you know that Bungie likes to hide sevens? The digits of the year 2032 add up to 7.

'''More tips'''

* You can replace each "logmessage" with a variable. In that case don't forget the = sign.
* Selection(0) means that from all selected objects the first one is taken.
* Use a loop to get all objects.

for each n in selection
logmessage n
next

* In order to shorten the code you might want to set script objects.
: The command to create a standard cube is ''CreatePrim "Cube", "MeshSurface"''
: If you use '''''set name = ''''' the cube or other object will be available under that ''name''.
: Then you can use any valid method or property with that ''name''.
: Example:

set c = CreatePrim ("Cube", "MeshSurface")

logmessage selection(0).name
logmessage selection(0).length.value
logmessage c.name
logmessage c.length.value

' INFO : cube
' INFO : 8
' INFO : cube
' INFO : 8

'''Some ModTool commands in vbs language that might be interesting for Oni related stuff'''

{| class="wikitable" width="100%"
| width=50% valign=top | LogMessage <nowiki>[string | var | object]</nowiki>
| A command to log information. It requires a string or a variable. Example:
: LogMessage "The object's name is: " & selection(0).Name
|-
| logmessage selection.count
| Logs the number of selected objects.
|-
| logmessage selection(0).Name
| Logs the object name.
|-
| logmessage selection(0).Materials(0).Name
| Logs the material name.
|-
| logmessage selection(0).Materials(0).Library.name
| Logs the material library name.
|-
| logmessage selection(0).Materials(0).shaders(0).name
| Logs the material shader (e.g. phong).
|-
|valign=top| logmessage selection(0).Materials(0).CurrentImageClip.source.filename.value
| Logs absolute path of the texture. Output example:
: ''C:\Users\RRM\Desktop\TV_tex.png''
|-
|valign=top| logmessage selection(0).Materials(0).CurrentImageClip.source.Parameters("XRes").Value logmessage selection(0).Material.CurrentImageClip.source.Parameters("YRes").Value
| Logs the horizontal (X) and vertical (Y) pixel length of the texture. Output example:
: ''512''
|-
| logmessage selection(0).sclx.value logmessage selection(0).scly.value logmessage selection(0).sclz.value
|valign=top| Logs object's scaling (X, Y, Z).
|-
| logmessage selection(0).rotx.value logmessage selection(0).roty.value logmessage selection(0).rotz.value
|valign=top| Logs object's rotation (X, Y, Z).
|-
| logmessage selection(0).posx.value logmessage selection(0).posy.value logmessage selection(0).posz.value
|valign=top| Logs object's position (X, Y, Z).
|-
|valign=top| logmessage selection(0).rotorder.value
| Logs object's rotation order. Oni characters have ZYX as rotation order.
:0 = XYZ
:1 = XZY
:2 = YXZ
:3 = YZX
:4 = ZXY
:5 = ZYX
|-
|valign=top| SelectObj <nowiki>[string | var]</nowiki>
| select one or more objects. Comma serves as separator. Example:
: SelectObj "grid,grid1"
|-
|valign=top| ToggleSelection <nowiki>[string | var]</nowiki>
| Adds one or more objects from current selection. If the objects are already selected then they become subtracted from the selection. Example:
: ToggleSelection "grid2,grid3"
|-
|valign=top| [https://download.autodesk.com/global/docs/softimage2013/en_us/sdkguide/index.html?url=si_cmds/SelectAllUsingFilter.html,topicNumber=si_cmds_SelectAllUsingFilter_html SelectAllUsingFilter] <nowiki>[SelFilter], [CheckComponentVisibility], [AffectSelectionList], [CheckObjectSelectability]</nowiki>
|Selects everything that matches the filter and other options. Example:
: SelectAllUsingFilter "object", siCheckComponentVisibility
:: selects all roots, lights, cameras, and geometry (meshes)
: SelectAllUsingFilter "geometry", siCheckComponentVisibility
:: selects all geometry (meshes)
|-
| DeselectAll
| deselects everything
|-
|valign=top| DeleteObj <nowiki>[string | var]</nowiki>
| Deletes one or more objects. Comma used as separator. Example:
: DeleteObj "grid"
: DeleteObj "grid,grid1"
|-
| FreezeObj
| Makes all changes final. But saving those changes is still necessary. (Click on key symbol so it gets red.)
|-
| [https://download.autodesk.com/global/docs/softimage2013/en_us/sdkguide/index.html?url=si_cmds/Translate.html,topicNumber=si_cmds_Translate_html Translate] <nowiki>[InputObjs], [X], [Y], [Z], [Delta], [RefMode], [Center], [AxesFilter], [Snap], [SnapReference], [SnapFilter], [SplitLocalComponents], [PropTagOnly], [Pivot], [PivotX], [PivotY], [PivotZ], [ConstructionMode], [SlideComponents]</nowiki>
| see link
|-
| [https://download.autodesk.com/global/docs/softimage2013/en_us/sdkguide/index.html?url=si_cmds/Rotate.html,topicNumber=si_cmds_Rotate_html Rotate] <nowiki>[InputObjs], [X], [Y], [Z], [Delta], [RefMode], [Center], [AxesFilter], [Reference], [SplitLocalComponents], [PropTagOnly], [Pivot], [PivotX], [PivotY], [PivotZ], [ConstructionMode], [SlideComponents]</nowiki>
| see link
|}

====Code pieces (VB Script)====
Remember that you can use the search function of your web browser.

If you see absolute paths adapt them so that the code works on your system too.

([[Mod_Tool/Scripting|Here]]'s another page for math related code pieces.)

{| class="wikitable" width="100%"
|width=33%| [1] creating and extending an array
|width=33%| [2] check selection mode
| [3] getting the IDs of selected polygons plus sorting them
|-
| [4] converting euler rotations (in degrees) to quaternions
| [5] converting quaternions to euler rotations (in degrees)
| [6] get and set values of the playcontrol (timeline)
|-
| [7] get keyframes
| [8] message box
| [9] input box
|-
| [10] getting the desktop path
| [11] selecting a folder
| [12] selecting a file of a specific type
|-
| [13] reading out environment variables
| [14] check if file exist
| [15] check if folder exist + create folder
|-
| [16] write xml file
| [17] read xml file
| [18] read xml file (attribute/content-based)
|-
| [19] create txt file + write lines
| [20] read txt file
| [21] check onisplit version
|-
| [22] call CMD, e.g. to use onisplit
| [23] building forms in ModTool
| [24] UserDataBlob
|-
| [25] getting the position of points (with selection mode point)
| [26] getting the position of points (with selection mode object)
| [27] getting and setting the position of points (without selection)
|-
| [28] getting the rotation and position of selected objects
| [29] getting the rotation and position of not selected objects
| [30] decrypting merged integer flags
|-
| [31] disabling PPG popups
| [32] disabling logmessages
| [33] getting bounding box values
|-
| [34] open an explorer window
| [35] working with hierarchies
| [36] drag and drop (DnD) support for specific oni files
|-
| [37] dae export
| [38] fbx export
| [39] import an image clip only once
|-
| [40] layers
| [41] onisplit update
| [42] get vertex color
|-
| [43] get all used textures
| [44] get global point position
|
|}

' '''[1] creating and extending an array'''

' creating an array
' () sets the number of array items
redim nums (3)
for i = 0 to 3
nums(i) = (i)
next

logmessage "output all items"
for each n in nums
logmessage n
next
logmessage "first array item holds: " & lbound(nums)
logmessage "last array item holds: " & ubound(nums)
logmessage "-------------------------------------"

' extending an array
' use "preserve" to keep the old content
' find next higher value
plus_one = ubound(nums) + 1
redim preserve nums (plus_one)
nums(plus_one) = 4

for each n in nums
logmessage n
next
logmessage "first array item holds: " & lbound(nums)
logmessage "last array item holds: " & ubound(nums)

' INFO : output all items
' INFO : 0
' INFO : 1
' INFO : 2
' INFO : 3
' INFO : first array item holds: 0
' INFO : last array item holds: 3
' INFO : -------------------------------------
' INFO : 0
' INFO : 1
' INFO : 2
' INFO : 3
' INFO : 4
' INFO : first array item holds: 0
' INFO : last array item holds: 4

' '''[2] check selection mode '''

checkfilter
'use sub to make use of the exit command

sub checkfilter
Select Case Selection.Filter.Name
'caution: case-sensitive

Case "object"
logmessage "object mode"
Case "Edge"
logmessage "edge mode"
Case "Vertex"
logmessage "point mode"
Case "Polygon"
logmessage "polygon mode"
Case Else
logmessage "unknown mode"
exit sub
End Select
end sub

' '''[3] getting the IDs of selected polygons plus sorting them'''

poly_count = Selection(0).SubComponent.ComponentCollection.count
logmessage "poly_count: " & poly_count
redim selected (poly_count)
logmessage "Show ID as it is."
for i=0 to poly_count - 1
' build ID array
selected(i) = Selection(0).SubComponent.ComponentCollection(i).index
logmessage selected(i)
next

' change sort order by replacing ">" with "<"
For i = 0 To poly_count - 1
For j = 0 To poly_count - 1
If selected(i) > selected(j) Then
tmp = selected(i)
selected(i) = selected(j)
selected(j) = tmp
End If
Next
Next
logmessage "Show sorted ID."

for i=0 to poly_count - 1
logmessage selected(i)
next

' '''[4] converting euler rotations (in degrees) to quaternions'''

dim x, y, z, dRotation, qRotation
x = 90
y = 0
z = 0

set dRotation = XSIMath.CreateRotation(XSIMath.DegreesToRadians(x), XSIMath.DegreesToRadians(y), XSIMath.DegreesToRadians(z))
set qRotation = XSIMath.CreateQuaternion()

dRotation.GetQuaternion (qRotation)
LogMessage qRotation.W
LogMessage qRotation.X
LogMessage qRotation.Y
LogMessage qRotation.Z
' INFO : 0,707106781186548
' INFO : 0,707106781186547
' INFO : 0
' INFO : 0

' '''[5] converting quaternions to euler rotations (in degrees)'''

dim qW, qX, qY, qZ, qRotation, x, y, z

qW = 0.707106781186548
qX = 0.707106781186547
qY = 0
qZ = 0

set qRotation = XSIMath.CreateQuaternion (qW, qX , qY, qZ)

qRotation.GetXYZAngleValues x, y, z
logmessage XSIMath.RadiansToDegrees(x)
logmessage XSIMath.RadiansToDegrees(y)
logmessage XSIMath.RadiansToDegrees(z)
' INFO : 89,9999999999999
' INFO : 0
' INFO : 0

' '''[6] get and set values of the playcontrol (timeline)'''

' timeline variables (tl)
dim tlStart, tlEnd, tlCurrent

' get values
tlStart = GetValue ("PlayControl.In")
tlEnd = GetValue ("PlayControl.Out")
tlCurrent = GetValue ("PlayControl.Current")

' set values
SetValue ("PlayControl.In"), 7
SetValue ("PlayControl.Out"), 70
SetValue ("PlayControl.Current"), 14

' '''[7] get keyframes'''

' keyframe counting code like "selection(0).rotx.Source.Keys.count" will produce an error if no keys exist
' that's why we need to catch possible errors for each counting

on error resume next
logmessage "--------------------------------------------------"
logmessage "X rotation keys: " & selection(0).rotx.Source.Keys.count
for each k in selection(0).rotx.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no X rotation keys"
end if
on error goto 0

on error resume next
logmessage "--------------------------------------------------"
logmessage "Y rotation keys: " & selection(0).roty.Source.Keys.count
for each k in selection(0).roty.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no Y rotation keys"
end if
on error goto 0

on error resume next
logmessage "--------------------------------------------------"
logmessage "Z rotation keys: " & selection(0).rotz.Source.Keys.count
for each k in selection(0).rotz.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no Z rotation keys"
end if
on error goto 0

on error resume next
logmessage "--------------------------------------------------"
logmessage "X position keys: " & selection(0).posx.Source.Keys.count
for each k in selection(0).posx.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no X position keys"
end if
on error goto 0

on error resume next
logmessage "--------------------------------------------------"
logmessage "Y position keys: " & selection(0).posy.Source.Keys.count
for each k in selection(0).posy.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no Y position keys"
end if
on error goto 0

on error resume next
logmessage "--------------------------------------------------"
logmessage "Z position keys: " & selection(0).posz.Source.Keys.count
for each k in selection(0).posz.Source.Keys
logmessage "index: " & k.index & " // time: " & k.time & " // value: " & k.value
next
if err <> 0 then
logmessage "no Z position keys"
end if
on error goto 0

' output example (0 rot keys, 2 pos keys):

' INFO : --------------------------------------------------
' INFO : no X rotation keys
' INFO : --------------------------------------------------
' INFO : no Y rotation keys
' INFO : --------------------------------------------------
' INFO : no Z rotation keys
' INFO : --------------------------------------------------
' INFO : X position keys: 2
' INFO : index: 0 // time: 2 // value: 5,14534318031942
' INFO : index: 1 // time: 6 // value: 8,2411504340802
' INFO : --------------------------------------------------
' INFO : Y position keys: 2
' INFO : index: 0 // time: 2 // value: 0,365325291829147
' INFO : index: 1 // time: 6 // value: 1,11923927115289
' INFO : --------------------------------------------------
' INFO : Z position keys: 2
' INFO : index: 0 // time: 2 // value: 1,96103417177471
' INFO : index: 1 // time: 6 // value: 1,88564277384233

' '''[8] message box'''

[https://download.autodesk.com/global/docs/softimage2013/en_us/sdkguide/index.html?url=si_om/XSIUIToolkit.MsgBox.html,topicNumber=si_om_XSIUIToolkit_MsgBox_html msgbox] "message", , "title"

' '''[9] input box'''

logmessage inputbox ("message", "title" , "pre-entered content")

' '''[10] getting the desktop path'''

' this can be useful for ''default locations'' like when selecting a folder
DesktopPath = CreateObject("WScript.Shell").SpecialFolders("Desktop")
logmessage DesktopPath

' '''[11] selecting a folder'''

' the default path is in this case my desktop
' to make it work on other systems, you would need the code of "getting the desktop path" section and replace my path with the ''DesktopPath''
logmessage XSIUIToolkit.PickFolder("C:\Users\RMM\Desktop\", "title" )

' '''[12] selecting a file of a specific type'''

set oFileBrowser = XSIUIToolkit.FileBrowser
oFileBrowser.DialogTitle = "Select an image file (png/tga/jpg)"
' (default folder)
oFileBrowser.InitialDirectory = "c:\"
oFileBrowser.Filter = "JPEG (*.jpg)|*.jpg|PNG (*.png)|*.png| Targa (*.tga)|*.tga||"
oFileBrowser.ShowOpen
If oFileBrowser.FilePathName <> "" Then
logmessage "User selected " & oFileBrowser.FilePathName
Else
logmessage "User pressed cancel"
End If

' '''[13] reading out environment variables'''

' some infos about env vars: [http://web.archive.org/web/20170309190841/http://softimage.wiki.softimage.com/xsidocs/config_envirovars.htm (1)], [http://web.archive.org/web/20180416194626/http://softimage.wiki.softimage.com/xsidocs/EnvVars_SettingandUsingEnvironmentVariables.htm (2)], [http://web.archive.org/web/20170617095054/http://softimage.wiki.softimage.com/xsidocs/EnvVars_EnvironmentVariableReference.htm (3)]
' those variables are stored inside the setenv.bat, two disadvantages:
' adding or editing those vars appears to not work in vbs or I just did it wrong
' anyway, new vars can only be read out after app restart
' therefore let's concentrate on reading out existing ones and then how to create our own via txt files (example: <nowiki>https://dl.dropbox.com/u/139715/OniGalore/ModToolScript/Oni_env_vars.txt Oni_env_vars.txt</nowiki> (dead link))
' code for reading out:
logmessage XSIUtils.ResolvePath("$SI_HOME/")

' '''[14] check if file exist'''

Set objFSO = CreateObject("Scripting.FileSystemObject")
If objFSO.FileExists ("C:\folder\file.txt") then
logmessage "File exists."
else
logmessage "File doesn't exist."
end if

' '''[15] check if folder exist + create folder'''

dim strDirectory
strDirectory = "C:\test"

Set objFSO = CreateObject("Scripting.FileSystemObject")
If objFSO.FolderExists(strDirectory) Then
Set objFolder = objFSO.GetFolder(strDirectory)
logmessage strDirectory & " already exists"
Else
Set objFolder = objFSO.CreateFolder(strDirectory)
logmessage "created folder " & strDirectory
End If

' ### or simply:
dir = "C:\test"
XSIUtils.EnsureFolderExists (dir)

' '''[16] write xml file'''

FolderName = CreateObject("WScript.Shell").SpecialFolders("Desktop")
FileName = "test"
FilePath = FolderName & "\OBAN" & FileName & ".xml"

Set oFS = CreateObject("Scripting.FileSystemObject")
Set objXMLFile = oFS.OpenTextFile(FilePath, 2, True, 0)

' quote sign in a string needs two quote signs
objXMLFile.WriteLine "<?xml version=""1.0"" encoding=""utf-8""?>"
objXMLFile.WriteLine "<Oni>"
objXMLFile.WriteLine "..."
objXMLFile.Close

' '''[17] read xml file'''

Set xmlDoc = CreateObject( "Microsoft.XMLDOM" )
xmlDoc.Async = "False"
path = "C:\Users\RRM\Oni\AE\AEInstaller\vanilla\level19_Final\BINACJBOWeapon.xml"
xmlDoc.Load( path )

Set colPosition = xmlDoc.selectNodes( "Oni/Objects/WEAP/Header/Position" )
Set colRotation = xmlDoc.selectNodes( "Oni/Objects/WEAP/Header/Rotation" )
Set colClass = xmlDoc.selectNodes( "Oni/Objects/WEAP/OSD/Class" )

loop_count = xmlDoc.selectNodes( "Oni/Objects/WEAP").length

logmessage "found " & loop_count & " weapons:"
logmessage "================"
for i=0 to loop_count - 1

'split string into pices as array, space is used as seperator by default
'element 0 = X; element 1 = Y; element 2 = Z
pos = split(colPosition.item(i).text)
rot = split(colRotation.item(i).text)

' Mod Tool wants comma instead of point for decimal seperator
pos(0) = replace (pos(0), ".", ",")
pos(1) = replace (pos(1), ".", ",")
pos(2) = replace (pos(2), ".", ",")

rot(0) = replace (rot(0), ".", ",")
rot(1) = replace (rot(1), ".", ",")
rot(2) = replace (rot(2), ".", ",")

logmessage colClass.item(i).text
logmessage pos(0) & " " & pos(1) & " " & pos(2)
logmessage rot(0) & " " & rot(1) & " " & rot(2)
logmessage "----------------"
next

' INFO : found 2 weapons:
' INFO : ================
' INFO : w5_sbg
' INFO : 23,16747 84,8193359 757,1958
' INFO : 0 0 0
' INFO : ----------------
' INFO : w4_psm
' INFO : 18,1105652 84,8193359 749,121
' INFO : 0 0 0
' INFO : ----------------

' '''[18] read xml file (attribute/content-based)'''

Set xmlDoc = CreateObject( "Microsoft.XMLDOM" )

' tells the program to wait until the file was loaded conpletely
xmlDoc.Async = "False"
xmlDoc.Load( "C:\Users\RRM\Oni\AE\AEInstaller\vanilla\level0_Final\BINAEINOimpact_effects.xml" )

' example 1 ('''we use this one''')
' nodes only with a certain attribute and conent will be collected

' content-based search: node [child_node = 'content']
' attribute-based search: node [@attribute_name = 'attribute_value']

' if things get too long an underscore _ can be used to make a linebreak
'''set w1_tap = xmlDoc.selectNodes _'''
'''( "Oni/ImpactEffects/Impact[@Name = 'w1_tap']/Material[@Name = 'Unbreak_Glass']/ImpactEffect [Component = 'Damage']" )'''

' example 2
' use "or" for a search of various material
'set w1_tap = xmlDoc.selectNodes _
' ( "Oni/ImpactEffects/Impact/Material[@Name = 'Default' or @Name = 'Character']/ImpactEffect" )

' example 3
' use (|) for a search of various content, e.g. ''<ImpactEffect><Modifier>Light'' plus ''<ImpactEffect><Modifier>Medium''
'set w1_tap = xmlDoc.selectNodes _
' ( "Oni/ImpactEffects/Impact/Material/(ImpactEffect [Modifier = 'Light'] | ImpactEffect [Modifier = 'Medium'])" )

for each element in w1_tap
logmessage "Impact: " & element.parentNode.parentNode.getAttribute("Name")
logmessage "Material: " & element.parentNode.getAttribute("Name")

' outputs "tag name: tag content"
logmessage element.childNodes(0).nodename & ": " & element.childNodes(0).text
logmessage element.childNodes(1).nodename & ": " & element.childNodes(1).text
logmessage "-----------------------------------"

'check for sounds
if element.childNodes(2).childNodes.length = 0 then
logmessage "sound not present"
else
logmessage "sound is present"
logmessage "-----------------------------------"
logmessage element.childNodes(2).childNodes(0).nodename & ": " & element.childNodes(2).childNodes(0).text
logmessage element.childNodes(2).childNodes(1).nodename & ": " & element.childNodes(2).childNodes(1).text
logmessage element.childNodes(2).childNodes(2).nodename & ": " & element.childNodes(2).childNodes(2).text
logmessage element.childNodes(2).childNodes(3).nodename & ": " & element.childNodes(2).childNodes(3).text
end if
logmessage "-----------------------------------"

' check for particle
if element.childNodes(3).childNodes.length = 0 then
logmessage "no particle present"
else
logmessage "number of particle: " & element.childNodes(3).childNodes.length
for each particle_section in element.childNodes(3).childNodes
logmessage "-----------------------------------"
for each particle_tag in particle_section.childnodes
logmessage particle_tag.nodename & ": " & particle_tag.text
next
next
end if
logmessage "==================================="
next

' INFO : Impact: w1_tap
' INFO : Material: Unbreak_Glass
' INFO : Component: Damage
' INFO : Modifier: Any
' INFO : -----------------------------------
' INFO : sound not present
' INFO : -----------------------------------
' INFO : number of particle: 2
' INFO : -----------------------------------
' INFO : Name: d__GLASSCRACK
' INFO : Orientation: 0
' INFO : Location: 4
' INFO : Decal1: false
' INFO : Decal2: true
' INFO : -----------------------------------
' INFO : Name: w1_tap_x03
' INFO : Orientation: 0
' INFO : Location: 1
' INFO : Offset: -1
' INFO : ===================================

' '''[] remove xml nodes'''

Set objXMLDoc = CreateObject("Microsoft.XMLDOM")
objXMLDoc.async = False

Dim XMLFile
XMLFile = "C:\Softimage\Softimage_Mod_Tool_7.5\OniLevels\ONLV\test\ONLVAirport.xml"
objXMLDoc.load(XMLFile)
Set nodes = objXMLDoc.selectNodes("Oni/CRSA/*")
For Each node In nodes
node.parentNode.removeChild(node)
Next

objXMLDoc.Save(XMLFile)

' '''[19] create txt file + write lines'''

txt_location = "C:\Softimage\Softimage_Mod_Tool_7.5\test.txt"
Set fso = CreateObject ("Scripting.FileSystemObject")
Set wText = fso.CreateTextFile (txt_location, 1)
wText.WriteLine "I'm a test file."
wText.WriteLine "Yo!"
wText.Close

' '''[20] read txt file'''

Set objFileToRead = CreateObject("Scripting.FileSystemObject").OpenTextFile("C:\Softimage\Softimage_Mod_Tool_7.5\test.txt", 1)

do while not objFileToRead.AtEndOfStream
strLine = objFileToRead.ReadLine()
logmessage strLine
loop
' INFO : I'm a test file.
' INFO : Yo!

objFileToRead.Close
Set objFileToRead = Nothing

' '''[21] check onisplit version'''

Set objFSO = CreateObject("Scripting.FileSystemObject")
logmessage objFSO.GetFileVersion("F:\Program Files (x86)\Oni\Edition\install\onisplit.exe")

' result looks like this:
' INFO : 0.9.59.0

' '''[22] call CMD, e.g. to lunch onisplit or the game'''

' relative path

' the "GameDataFolder" isn't inside the "install" folder
' so we will use ..\ to go one folder backwards

' additional quote signs tells the program where the
' paths strings start and end in case the path contains spaces

' if you are going to use the xml file right after its extraction (which is likely)
' then the "/wait" argument inside the onisplit_action string is important
' without it the code would continue and might try to read the not existing xml file and produce an error

onisplit_location = "F:\Program Files (x86)\Oni\Edition\install"
input_folder = """..\GameDataFolder\level19_Final\ONLVcompound.oni"""
output_folder = """..\GameDataFolder"""
onisplit_action = "cmd /C start /wait OniSplit.exe -extract:xml " & output_folder & " " & input_folder
logmessage "relative path: " & onisplit_action
' expected logmessage:
' INFO : relative path: cmd /C start OniSplit.exe -extract:xml "..\GameDataFolder" "..\GameDataFolder\level19_Final\ONLVcompound.oni"
XSIUtils.LaunchProcess onisplit_action, 1, onisplit_location

' absolute path

'adapt paths so it works on your computer
onisplit_location = "F:\Program Files (x86)\Oni\Edition\install"
input_folder = """F:\Program Files (x86)\Oni\Edition\GameDataFolder\level19_Final\ONLVcompound.oni"""
output_folder = """F:\Program Files (x86)\Oni\Edition\GameDataFolder"""
onisplit_action = "cmd /C start /wait OniSplit.exe -extract:xml " & output_folder & " " & input_folder
logmessage "absolute path: " & onisplit_action
' expected logmessage:
' INFO : absolute path: cmd /C start OniSplit.exe -extract:xml "F:\Program Files (x86)\Oni\Edition\GameDataFolder" "F:\Program Files (x86)\Oni\Edition\GameDataFolder\level19_Final\ONLVcompound.oni"
XSIUtils.LaunchProcess onisplit_action, 1, onisplit_location

' you can also lunch bat files

onibat = "cmd /C start run_wind.bat"
onilocation = "F:\Program Files (x86)\Oni\Edition"
XSIUtils.LaunchProcess onibat, 0, onilocation

' alternative to cmd: call onisplit via winmgmts

' slightly modified code from [https://devblogs.microsoft.com/scripting/how-can-i-start-a-process-and-then-wait-for-the-process-to-end-before-terminating-the-script/ that site]
' ''logmessage "onisplit finished."'' will be executed after the conversion finished, there should be also an delay of 3 seconds to support very slow computers
' if you are going to use this method consider to extent the code to check if input file and output directory exist
osp_loca = "C:\OniAE\Edition\install\OniSplit.exe"
osp_action = "-extract:xml"
osp_output = """C:\OniAE\Edition\GameDataFolder"""
osp_input = """C:\OniAE\Edition\GameDataFolder\level1_Final\AKEVEnvWarehouse.oni"""
osp_total = osp_loca & " " & osp_action & " " & osp_output & " " & osp_input
logmessage osp_total

strComputer = "."
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2:Win32_Process")
objWMIService.Create osp_total, null, null, intProcessID
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")

' wait 3 second to find event - should be enough time for single actions on a slow computer
Set colMonitoredProcesses = objWMIService.ExecNotificationQuery _
("Select * From __InstanceDeletionEvent Within 3 Where TargetInstance ISA 'Win32_Process'")

Do Until i = 1
Set objLatestProcess = colMonitoredProcesses.NextEvent
If objLatestProcess.TargetInstance.ProcessID = intProcessID Then
i = 1
End If
Loop
logmessage "onisplit finished."
' now you can work with the extracted xml file

[[Image:XSI_Mod_Tool_PPG.png|thumb]]

' '''[23] building a form (PPG)'''

dim oPSet, oPPGLayout, oItem, PPG_exist

' set check value to 0
PPG_exist = 0

' check if PPG exists
for each prop in ActiveProject.ActiveScene.Root.Properties
logmessage prop.name
if instr(1, prop.name, "my_new_PPG") > 0 then
PPG_exist = 1
logmessage "found " & """" & prop.name & """"
end if
next

' create PPG if it doesn't exist
if PPG_exist = 0 then
set oPSet = ActiveSceneRoot.AddProperty("CustomProperty", false, "my_new_PPG")
set oPPGLayout = oPSet.PPGLayout

' setup PPG parameters
' ###################################################################################
' create checkbox and remove key symboles by setting parameter "Animatable" to false
oPSet.AddParameter3 "Check1", siBool, 0, , , false
oPSet.AddParameter3 "Check2", siBool, 0, , , false
oPSet.AddParameter3 "Check3", siBool, 1, , , false
oPSet.AddParameter3 "Check4", siBool, 1, , , false
oPSet.AddParameter3 "text1", siString
' last parameter of "int1" is set to ReadOnly
oPSet.AddParameter3 "int1", siInt2, , , , false, 1
oPSet.AddParameter3 "int2", siInt2, , , , false, 0

' add PPG items
' ###################################################################################
oPPGLayout.AddItem "text1", "Hi there!"
oPPGLayout.AddItem "int1", "number 1"
oPPGLayout.AddItem "int2", "number 2"
oPPGLayout.AddGroup "4 checkboxes", true
oPPGLayout.AddRow
oPPGLayout.AddItem "Check1", "C1"
oPPGLayout.AddItem "Check3", "C3"
oPPGLayout.EndRow
oPPGLayout.AddRow
oPPGLayout.AddItem "Check2", "C2"
oPPGLayout.AddItem "Check4", "C4"
oPPGLayout.EndRow
oPPGLayout.EndGroup

oPPGLayout.AddButton("log_values", "log PPG values").setAttribute siUICX, 120

oPPGLayout.Logic = "sub log_values_OnClicked" & vbCrlf & _
" logmessage ""text 1 = "" & getvalue(""my_new_PPG.text1"")" & vbCrlf & _
" logmessage ""number 1 = "" & getvalue(""my_new_PPG.int1"")" & vbCrlf & _
" logmessage ""C1 = "" & getvalue(""my_new_PPG.Check1"")" & vbCrlf & _
" end sub"

oPPGLayout.Language = "VBScript" 'Optional because this is the default

' open PPG
InspectObj oPSet
else
' open that PPG if it already exist
InspectObj "my_new_PPG"
end if

' set values from outside the PPG
setvalue "my_new_PPG.text1", "any text could stand here"
setvalue "my_new_PPG.int1", "42"
setvalue "my_new_PPG.check1", true

' get values from outside the PPG
logmessage getvalue("my_new_PPG.text1")
logmessage getvalue("my_new_PPG.int1")
logmessage getvalue("my_new_PPG.check1")

[[Image:XSI_Mod_Tool_UserDataBlob.png|thumb]]

' '''[24] UserDataBlob'''

' you can attach data to objects, e.g. new properties for the scene root or Oni Trigger Volumes
' the so-called "UserDataBlob" can't be saved in *.dae, so save the whole scene to keep your progress

' check if my property exist
found_my_prop = 0
set oProps = ActiveProject.ActiveScene.Root
logmessage "root name: " & ActiveProject.ActiveScene.Root
for each prop in oProps.Properties
' remove apostroph in line beneath to log all root properties
'LogMessage prop.Name
if instr(1, prop.Name, "my_prop") = 1 then
found_my_prop = 1
end if
next

' prop doesn't exist, create it
if found_my_prop = 0 then
' create property (must also have content, in this case "yes")
oProps.AddProperty( "UserDataBlob", , "my_prop" ).value = "yes"
logmessage "created my new prop"
end if

' prop exists, change/read its value
if found_my_prop = 1 then
' change property
oProps.Properties( "my_prop" ).value = "no"

' read property
logmessage oProps.Properties( "my_prop" ).value
' if you want to read a property from another script be sure that it was already created
' reuse code under "check if my property exist"
end if

' '''[25] getting the position of points (with selection mode point)'''

' a point must be selected
' gets xyz position of first selected point of the first selected object
logmessage Selection(0).SubComponent.ComponentCollection(0).position.x
logmessage Selection(0).SubComponent.ComponentCollection(0).position.y
logmessage Selection(0).SubComponent.ComponentCollection(0).position.z

' '''[26] getting the position of points (with selection mode object)'''

' an object must be selected
' gets xyz position of point 0 of the first selected object
logmessage selection(0).activeprimitive.geometry.Points(0).Position.x
logmessage selection(0).activeprimitive.geometry.Points(0).Position.y
logmessage selection(0).activeprimitive.geometry.Points(0).Position.z

' '''[27] getting and setting the position of points (without selection) right after object creation'''

' point positions are relative to the object's center
' to get the absolute point positions add center to point
' to set the absolute point positions subtract center from point

set oRoot = application.activeproject.activescene.root
set oObj = oRoot.addgeometry( "Cube", "MeshSurface", "test" )

' to test our code move center to somewhere else
Translate oObj, 9, 11, 13, siRelative, siGlobal, siCtr, siXYZ, , , , , , , , , , 0
SaveKey oObj & ".kine.local.posx," & oObj & ".kine.local.posy," & oObj & ".kine.local.posz", 1, , , , True

FreezeObj oObj
set oGeometry = oObj.activeprimitive.geometry
aPositions = oGeometry.Points.PositionArray
' get old position
' (xyz, point)
logmessage "old point 0 posx: " & aPositions(0, 0) + GetValue(oObj & ".kine.global.posx")
logmessage "old point 0 posy: " & aPositions(1, 0) + GetValue(oObj & ".kine.global.posy")
logmessage "old point 0 posz: " & aPositions(2, 0) + GetValue(oObj & ".kine.global.posz")

' set new position
aPositions(0, 0) = -7 - GetValue(oObj & ".kine.global.posx")
aPositions(1, 0) = -7 - GetValue(oObj & ".kine.global.posy")
aPositions(2, 0) = -7 - GetValue(oObj & ".kine.global.posz")

' update the array
oGeometry.Points.PositionArray = aPositions
' get new position
logmessage "new point 0 posx: " & aPositions(0, 0) + GetValue(oObj & ".kine.global.posx")
logmessage "new point 0 posy: " & aPositions(1, 0) + GetValue(oObj & ".kine.global.posy")
logmessage "new point 0 posz: " & aPositions(2, 0) + GetValue(oObj & ".kine.global.posz")

' INFO : old point 0 posx: -4
' INFO : old point 0 posy: -4
' INFO : old point 0 posz: -4

' INFO : new point 0 posx: -7
' INFO : new point 0 posy: -7
' INFO : new point 0 posz: -7

' '''[28] getting the scaling, rotation and position of selected objects'''

logmessage "mesh name: " & selection(0)
logmessage selection(0).sclx.value
logmessage selection(0).scly.value
logmessage selection(0).sclz.value
logmessage selection(0).rotx.value
logmessage selection(0).roty.value
logmessage selection(0).rotz.value
logmessage selection(0).posx.value
logmessage selection(0).posy.value
logmessage selection(0).posz.value

' '''[29] getting the scaling, rotation, and position of not selected objects'''

' GetValue("NAME.kine.global.rotx")
' NAME must be the exact mesh name
' let's say you want the data of one character's pelvis
logmessage GetValue("pelvis.kine.global.sclx")
logmessage GetValue("pelvis.kine.global.scly")
logmessage GetValue("pelvis.kine.global.sclz")
logmessage GetValue("pelvis.kine.global.rotx")
logmessage GetValue("pelvis.kine.global.roty")
logmessage GetValue("pelvis.kine.global.rotz")
logmessage GetValue("pelvis.kine.global.posx")
logmessage GetValue("pelvis.kine.global.posy")
logmessage GetValue("pelvis.kine.global.posz")

' '''[30] decrypting merged integer flags'''

' for example the [[XML:BINA/OBJC/TRGV|BINACJBOTrigger Volume.xml]] file has flags as strings for the <Flags> tag
' and integer values for the <Teams> tag whereby the values are merged to one value
' so if <Teams> tag holds "101" we have to think what flags it holds, the flags can be broken down with following code

' x: hypothetical value of <Teams>
x=101
' 101 = 64 + 32 + 4 + 1

x_255
sub x_255
if x > 255 then
msgbox "Flags bigger than 255 are not allowed.", ,"error"
exit sub
end if
if x >= 128 and x <= 255 then
logmessage "128"
x = x - 128
end if
if x >= 64 and x < 128 then
logmessage "64"
x = x - 64
end if
if x >= 32 and x < 64 then
logmessage "32"
x = x - 32
end if
if x >= 16 and x < 32 then
logmessage "16"
x = x - 16
end if
if x >= 8 and x < 16 then
logmessage "8"
x = x - 8
end if
if x >= 4 and x < 8 then
logmessage "4"
x = x - 4
end if
if x >= 2 and x < 4 then
logmessage "2"
x = x - 2
end if
if x = 2 then
logmessage "2"
x = x - 2
end if
if x = 1 then
logmessage "1"
x = x - 1
end if
if x = 0 then
logmessage "finished check"
end if
end sub

' INFO : 64
' INFO : 32
' INFO : 4
' INFO : 1
' INFO : finished check

' '''[31] disabling PPG popups'''

' for example if code of a script button creates numerous objects in one go, the same number of property pages (PPG) can appear
' for user convenience those PPG popups can be disabled

' disable PPG popup
Preferences.SetPreferenceValue "Interaction.autoinspect", false

' creates the cube mesh but no PPG will show up
CreatePrim "Cube", "MeshSurface"

' enable PPG popup again
Preferences.SetPreferenceValue "Interaction.autoinspect", true

' '''[32] disabling logmessages'''

' msglogverbos is probably already set to false by default
' could be set at the start of a final script to increase performance
setvalue "preferences.scripting.msglogverbose", false
setvalue "preferences.scripting.msglog", false

' '''[33] getting bounding box values'''

' this could be useful to create a bounding box for [[XML:OFGA|OFGA files]]

' let's get the bounding box of a simple cylinder
' the output values will be absolute positions
CreatePrim "Cylinder", "MeshSurface"

dim xmin, ymin, zmin, xmax, ymax, zmax
dim list
'if you use SelectionList the objects will be treated as one single object
'set list = GetValue( "SelectionList" )
set list = GetValue( selection(0) )
GetBBox list, TRUE, xmin, ymin, zmin, xmax, ymax, zmax
LogMessage "Lower Bound: " & xmin & " / " & ymin & " / " & zmin
LogMessage "Upper Bound: " & xmax & " / " & ymax & " / " & zmax

' expected output:
' INFO : Lower Bound: -1 / -2 / -1
' INFO : Upper Bound: 1 / 2 / 1

' '''[34] open an explorer window'''

' this could be used open an output folder ...
strPath = "[http://web.archive.org/web/20150212074443/http://support.microsoft.com/kb/152457 explorer.exe /e]," & XSIUtils.ResolvePath("$SI_HOME/")
Set objShell = CreateObject("Wscript.Shell")
objShell.Run strPath

' to select a generated file inside the folder:
strPath = "explorer.exe /select," & "C:\folder\test.txt"

[[Image:XSI_Mod_Tool_SelectNeighborObj_obj_5.png|thumb|SelectNeighborObj obj 5]]
' '''[35] working with hierarchies'''

' let's be sure we have an object selected
if selection.count > 0 and typename(selection(0)) = "X3DObject" then

' the object itself
logmessage selection(0)

' the parent object
logmessage selection(0).parent

' the children
for each n in selection(0).FindChildren( , , , 0 )
logmessage n
next
' the 4the parameter of FindChildren can be set to 0 or 1
' with 0 you get all direct children
' with 1 you get everything located under that object no matter how deep the level

' count all objects
logmessage "children: " & selection(0).FindChildren( , , , 1).count
' caution: if the 3rd parameter is set to siMeshFamily
' then the selected object will be also counted

' find the root object of the hierarchy, any object could be selected
SelectNeighborObj selection(0), 4

' go through the hierarchy in different directions
' SelectNeighborObj [parameter1], [parameter2], [parameter3], [parameter4]
' options of the second parameters
' 0 go one level up
' 1 go one level down
' 2 go to next silbing
' 3 go to previous silbing
' 4 go to highest level
' 5 go to deepest level of current selected obj
' 5: if there are more than one children, the path goes always for the first (left) child (see image)

' select the hierarchy as a whole
SelectObj "left_thigh", "TREE", true
' first parameter could be any object of the hierarchy
' after using this the selection of an Oni character will be "B:pelvis"
else
msgbox "no object was selected"
end if

'''[36] drag and drop support for specific oni files'''

function XSILoadPlugin( in_reg )
in_reg.Author = ""
in_reg.Name = "Oni drag and drop support"
in_reg.Email = ""
in_reg.URL = ""
in_reg.Major = 1
in_reg.Minor = 0

in_reg.RegisterEvent "support_oni_DnD",siOnDragAndDrop
'RegistrationInsertionPoint - do not remove this line

XSILoadPlugin = true
end function

function XSIUnloadPlugin( in_reg )
dim strPluginName
strPluginName = in_reg.Name
Application.LogMessage strPluginName & " has been unloaded.",siVerbose
XSIUnloadPlugin = true
end function

function support_oni_DnD_OnEvent( in_ctxt )
Set objFSO = CreateObject("Scripting.FileSystemObject")

FullFilePath = in_ctxt.GetAttribute("DragSource")
FileExt = objFSO.GetExtensionName(FullFilePath)
FileName = objFSO.GetBaseName(FullFilePath)

if instr(LCase(FileExt), "oni") = 1 then
in_ctxt.SetAttribute "DragSourceSupported", true

' next line prevents the code from being repeated
if in_ctxt.GetAttribute("DragAndDropAction") = 1 then

logmessage "What I'm supposed to do with that oni?"
' do more stuff here
' ..................
' e.g. telling onisplit to extract the oni

end if
end if

support_oni_DnD_OnEvent = true
end function

'''Important:'''

Mod Tool has its own drag and drop event handler for dae and xml file.

If we succeed in modifying and shipping that new file, we could finally trigger scripts with those files and process them.

The original file can be found at:
logmessage XSIUtils.ResolvePath("$XSI_HOME/") & "Application\DSScripts\Model.vbs"
' C:\Softimage\Softimage_Mod_Tool_7.5\Application\DSScripts\'''Model.vbs'''
A backup of the original file can be found here: '''<nowiki>https://dl.dropboxusercontent.com/u/139715/OniGalore/ModToolScript/Model.vbs</nowiki> (dead link)'''

There are two issues that can be fixed by modifying this file.
* import of xml files created by onisplit
* import of dae and xml files with relative path from a html page

Relative file pathes will be transformed to absolute pathes whereby an unwanted "file:///" is added.

A solution to is to transform the path again.

if instr(in_Filename,"file:///") = 1 then
in_Filename = replace(in_Filename, "file:///", "")
end if

Following function is always triggered, so we will modify it.
sub ImportDotXSIProc( in_Filename, in_Parent )
if instr(in_Filename,"file:///") = 1 then
in_Filename = replace(in_Filename, "file:///", "")
end if
Set objFSO = CreateObject("Scripting.FileSystem<Object")
FileExt = objFSO.GetExtensionName(in_Filename)

if application.license = "Avid 3D" then
SIImportDotXSIFile in_Filename, in_Parent
else
Set oFS = CreateObject("Scripting.FileSystemObject")
if oFS.FileExists(in_Filename) = True then
if FileExt = "xml" then
' is this an Oni xml file ?
Set xmlDoc = CreateObject("Microsoft.XMLDOM")
xmlDoc.Async = "False"
xmlDoc.Load(in_Filename)
if xmlDoc.selectNodes("Oni").length > 0 then
logmessage "Oni xml file detected"
read_xml "OFGA", in_Filename
end if
exit sub
end if

The lines in red has been added.

'''[37] dae export'''

set oProps = ActiveProject.ActiveScene.Root.Properties
if typename (oProps.find("ExportCrosswalkOptions")) = "Nothing" then
logmessage "Export settings not set"
CreateExportCrosswalkOptions , "ExportCrosswalkOptions"
else
logmessage "Export settings present"
end if

' sets the extension to dae
SetValue "ExportCrosswalkOptions.Format", 1
' set export path and file name
SetValue "ExportCrosswalkOptions.Filename", CreateObject("WScript.Shell").SpecialFolders("Desktop") & "\export_test.dae"
' selection only
SetValue "ExportCrosswalkOptions.ExportSelectionOnly", True
' export
ExportCrosswalk "ExportCrosswalkOptions"

'''[38] fbx export'''

FBXExportLights (false)
FBXExportSelection (true)
' mark FBXExport and hit F1 to get more options
FBXExport (CreateObject("WScript.Shell").SpecialFolders("Desktop") & "\export_test.fbx" )

'''[39] import an image clip only once'''

image_path = "C:\Users\RRM\Desktop\white_512_512.tga"

Set FSO = CreateObject("Scripting.FileSystemObject")
image_clip = FSO.GetBaseName(image_path) & "_" & FSO.GetExtensionName(image_path)
logmessage image_clip

if not typename(ActiveProject.ActiveScene.ImageClips(image_clip)) = "Nothing" then
logmessage "found image clip"
else
logmessage "image clip not yet present, going to import ..."

SICreateImageClip image_path
' or as script object:
'set oImage = AddImageSource (image_path)
'set oImageClip = AddImageClip (oImage)
end if

'''[40] layers'''

[[Image:ModTool_layers.png|thumb|200px|right|how to access scene layers]]

To access scene layers switch from Main Control Panel (MCP) to Keying Panel/Layers (KP/L) and then click "Scene".

After the user became used to layers, they can help to organize work in a scene. This is especially interesting for some scripting tasks like getting TRGV/FURN data for xml files.

' get current layer
GetCurrentLayer CurrentLayer
logmessage CurrentLayer

' create a new layer named "FurnLayer" if it doesn't already exist
' make new layer the current layer
if typename(ActiveProject.ActiveScene.Layers("FurnLayer")) = "Nothing" then
SICreateLayer , "FurnLayer", FurnLayer
SetCurrentLayer FurnLayer
else
SetCurrentLayer "Layers.FurnLayer"
end if

' get objects in FurnLayer and count objects
' exit sub if there are no objects
SelectMembers "Layers.FurnLayer"
if selection.count = 0 then
MsgBox "No OFGA data found to export.", , "Export canceled"
exit sub
end if

' if there are Furn objects
for each obj in selection
' do something e.g. create xml
next

' '''[41] onisplit update'''

' this downloads and unzips the last attachment from the [http://mods.oni2.net/node/38 onisplit page]
output_dir = "F:\test\"

' get onisplit link ################################################
set xmlhttp = createobject ("msxml2.xmlhttp.3.0")
xmlhttp.open "get", "http://mods.oni2.net/node/38/index.html", false
xmlhttp.send

<nowiki>webtext = xmlhttp.responseText
webtext = replace(replace(webtext, vbcr,""),vblf,"")
webtext = split(webtext, "<table class=""sticky-enabled""> <thead><tr><th>Attachment</th>" )(1)
webtext = split(webtext, "</td> </tr></tbody></table>") (0)</nowiki>

link_start = instrrev(webtext, "http")
link_end = instrrev(webtext, ".zip"" type") + 4 ' + zip
' mid (text, begin, length)
link = mid(webtext, link_start, link_end - link_start)
logmessage "last link in attachment: " & link

dim xHttp: Set xHttp = createobject("Microsoft.XMLHTTP")
dim bStrm: Set bStrm = createobject("Adodb.Stream")
xHttp.Open "GET", link, False
xHttp.Send

' get file name ###################################################
hdr = xHttp.getResponseHeader("Content-Disposition")
hdr = replace (hdr, "attachment; filename=""", "")
hdr = replace (hdr, """", "")
logmessage hdr

' save file #######################################################
filename = output_dir & hdr
with bStrm
.type = 1 '//binary
.open
.write xHttp.responseBody
.savetofile filename, 2 '//overwrite
end with

' extract file ####################################################

UnzipFile filename, output_dir

Function UnzipFile(ZipFile, ExtractTo)
Set fso = CreateObject("Scripting.FileSystemObject")
If NOT fso.FolderExists(ExtractTo) Then
fso.CreateFolder(ExtractTo)
End If
set objShell = CreateObject("Shell.Application")
set FilesInZip=objShell.NameSpace(ZipFile).items
objShell.NameSpace(ExtractTo).CopyHere(FilesInZip)
Set fso = Nothing
Set objShell = Nothing
End Function

' '''[42] get vertex color'''

set oGeometry = selection(0).activeprimitive.geometry
set oTriangles = oGeometry.Triangles

for each oTriangle in oTriangles
logmessage oTriangle.Name

for each oVertex in oTriangle.Points
set oColor = oVertex.Color
logmessage vbTab & "RGBA(" & _
oColor.red & "," & _
oColor.green & "," & _
oColor.blue & "," & _
oColor.alpha & ")"
next
next

' '''[43] get all used textures'''

DeleteAllUnusedMaterials
DeleteUnusedImageClips
'DeleteUnusedImageSources
for each i in Application.ActiveProject.ActiveScene.ExternalFiles
if i.filetype = "Pictures" then
logmessage i
end if
next

' ''' [44] get global point position'''

set oObj = selection(0)
set oTrans = oObj.Kinematics.Local.Transform
set oPoint0 = oObj.ActivePrimitive.Geometry.Points(0)
set oPoint7 = oObj.ActivePrimitive.Geometry.Points(7)
set oPos0 = oPoint0.Position
set oPos7 = oPoint7.Position

' scaling must be frozen to 1 before we can calculate the size from local values
ResetTransform selection(0), siCtr, siScl, siXYZ

logmessage "local p0: "& oPos0.X & " " & oPos0.Y & " " & oPos0.Z
set oGlobalPos0 = XSIMath.MapObjectPositionToWorldSpace( oTrans, oPos0)
logmessage "global p0: "& oGlobalPos0.X & " " & oGlobalPos0.Y & " " & oGlobalPos0.Z

logmessage "local p7: "& oPos7.X & " " & oPos7.Y & " " & oPos7.Z
set oGlobalPos7 = XSIMath.MapObjectPositionToWorldSpace( oTrans, oPos7)
logmessage "global p7: "& oGlobalPos7.X & " " & oGlobalPos7.Y & " " & oGlobalPos7.Z

logmessage "size: " & oPos7.X - oPos0.X & " " & _
oPos7.Y - oPos0.Y & " " & _
oPos7.Z - oPos0.Z
' with a rotation of: -3,8792 16,4039 -13,5017
' INFO : local p0: -4 -4 -4
' INFO : local p7: 4 4 4
' INFO : global p0: -5,74764582364017 -3,00250371537919 -2,43916767056426 ' TRGV start point
' INFO : global p7: 5,74764582364017 3,00250371537919 2,43916767056426
' INFO : size: 8 8 8

===Interactive Creative Environment (ICE)===
* [[wikipedia:Autodesk_Softimage#ICE_Interactive_Creative_Environment|ICE]]

'''tutorials:'''
* https://www.youtube.com/watch?v=ioMQ2rBVO4g
* http://dot3d.blogspot.com/2009/10/softimage-ice-tree-building-step-by.html
* [https://www.si-community.com/community/viewtopic.php?f=41&t=1707 an ICE tutorial thread]
* [https://download.autodesk.com/global/docs/softimage2013/en_us/userguide/index.html?url=files/ICE_trees_DebuggingICETrees.htm,topicNumber=d30e269791 ICE trees Debugging]
* <nowiki>https://support.solidangle.com/display/SItoAUG/ICE</nowiki> (dead link)

==Wanted knowledge==
* How to set up particles in Mod Tool? We still need an Oni particle editor!
* How to rig models and then extract the animation data?
* How to make complex new UV maps?

[[Category:Modding tutorials]][[Category:Outdated modding tools]][[Category:Windows-only modding tools]]

User:Vortice

2025-01-22T19:16:16Z

Vortice: Created page with "I'm an idiot without any noticeable contribution to society. For now."

I'm an idiot without any noticeable contribution to society. For now.

Modding errors

2025-01-22T18:53:18Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: FAQ -> Why are body parts overlapping}}
You might want to use the browser's search function to quickly find an error message.
{{TOClimit|3}}

==Frequently asked questions==
[[Image:modding_errors.jpg|thumb|200px]]

*Why does Oni crash on game start?
::What were you working on? A [[#... due to overloaded animation|character animation]]?
*Why does Oni crash while loading a level?
::What were you working on? A [[#... due to missing files|game level]]?
*Why does a character have black body parts?
::You're probably [[#Missing character texture (TXMP)|missing a texture]].
*Why does a character have white body parts?
::You are using a mod with bgra32 textures and an old engine that doesn't support bgra32.
* Why can't I convert character animations?
::See [[#TRAM-related|HERE]] if you use "-create:tram".
* Why are all body parts overlapping in the DAE file?
::Because the part hierarchy isn't correct. Read more [https://web.archive.org/web/20160225191109/http://oni.bungie.org/forum/viewtopic.php?pid=31310#p31310 here].

==Visual errors based on settings==
===Black splashscreens but normal gameplay===
Those screens (all TXMBs) are black if the user has a lower resolution than the screen. Oni's vanilla splashscreens are 640x480 but the [[AE]]'s "HD Screens" package bumps them up to 1024x768, which is where players usually encounter this problem.

'''Note''': This problem is fixed by [[Daodan DLL]] v3.5 or newer and the [[FERAL|Mac Intel build]] v1.2 or newer.

==Binary errors==
===Crash while starting Oni===
====... due to overloaded animation====
Animations with more than 107 keys per bone crash the game. You can import animations with more than 107 frames if the keys cover multiple frames.
: For example 12 frames ''<EKey>'''12''' -156.628983 -14.6175327 -78.3831558</EKey>''
Such ranges and EKeys are produced by older OniSplit versions. See [[#TRAM-related|HERE]].

'''Note:''' You shouldn't encounter this bug anymore with OniSplit v0.9.56.0 or newer.

===Crash while loading a level===
====... due to improper textures====
Textures' x and y (pixel) dimensions must be a power of two: 512, 256, 128, 64, etc.

====... due to missing files====
Generally it can be said that Oni complains when an instance is missing that is referenced by another instance. For instance:
* AKEVs don't tolerate missing textures.
* ONVLs and ONCCs don't tolerate missing variants (ONCVs).

====... due to triangle limit====
* with too many triangles, Oni crashes after ~90% of the loading process; the triangle limit is ~520,000 (500,000 to be on the safe side).

===Crash while playing===
====... due to missing files====
If you encounter a crash when spawning a character or when you cycle through all characters with F8, then check if the crashing character has a TRMA file.

===Non-crash errors===
These errors are visible inside the game and don't cause a crash when they appear.

====Multiple savegame names for same level number====
The Load Game menu can show additional savegame names if any new ONLV is provided in another level0 plugin. As a quick test, you should use a plugin name which comes alphabetically before "level0_Final", such as "level0_Addin". If you choose a name like "level0_More", the new savegame will be appended after all "_Final" ONLDs, and also a clone appears:

: "_Final" list
: new savegame name from "_More"
: cloned savegame name of the slot meant to be overwritten

====Multiple TXMBs====
A level can start with multiple TXMBs, visible one by one, although there was just one BSL command calling for one. This is caused by using additional plugins, because files with the same name can stack.

====Missing character texture (TXMP)====
The texture is either missing, or the texture name and the link in [[OBD:TRMA|TRMA]] do not match.

====Distorted colors in textures (TXMP)====
[[Image:color_spectrum_test.jpg|thumb|200px]]

Why do my source and re-extracted textures look okay but in-game the colors are distorted? The "[[OBD_talk:TXMP#0x_00_10_00_00|little endian data]]" flag in the level data file is missing. The flag will be added by OniSplit v0.9.56.0 or later when you import it, or you can create the TXMP via an XML file and ensure that the flag is present before import.

====Missing animation collection (TRAC)====

====Missing 3D model (TRBS)====

====Distorted 3D model (TRBS)====
[[Image:XSI_Konoko_Ref.png|thumb|200px]]

When creating the 3D model in Mod Tool, you have to watch out for the naming and order of the body parts.
* If you use OniSplit v0.9.58.0 or lower, the naming of body parts must be absolutely correct.
* If you use higher versions, the naming is unimportant but the order matters. The order can be easily changed in the Schematic [9]. Then go to Edit > [http://edt.oni2.net/images/schematic.jpg Reorder Nodes Tool] [I] and move an object to its new position.

====Non-working combos (TRAM)====
Situation: When you create combos, you want to test your moves in-game. Sometimes each move actually works (tested via chr_animate) but the combo does not.

Requirements to prevent that bug:
* <Attacks> and <HorizontalExtents> data is needed
** '''Note:''' With OniSplit v0.9.55.0 or newer, HorizontalExtents (now named "[[XML:TRAM#List_of_tags.2C_types.2C_and_flags|AttackRing]]") is calculated automatically.
* Correct links to the Direct Animations tag
* Correct links inside the character's animation collection (TRAC)

==Developer Mode error messages==
===Animation errors===
''throwtarget was NULL'' - The throw target animation was not found.

===BSL errors===
*''Func "main", File "(called from engine)", Line 0: semantic error, '''function''' "main" '''does not exist''''', then either the function "main" wasn't found in any BSL file (this can also happen with any other function), or the BSL file has too many commands in it (see [[#BSL_commands_per_file_limitation|here]]). If it's the latter, split your BSL file into more BSL files (creating additional functions if necessary).

* ''Func "(null)", File "test.bsl", Line 3: semantic error, '''Identifier''' "main" already declared'' - In this example, there are multiple "main" functions; the last occurrence of main() can be found in the file "test.bsl" at line 3.

* ''Func "(null)", File "main.bsl", Line 1: Illegal token, got "func" expected ";"'' - A previous variable declaration didn't end with a semicolon.

* ''SLiSchedule_Task_Find FAILED [IMPORTANT]'' - The game will freeze after about 5 instances of this message. Caused by calling too many BSL functions in parallel (using fork) in a very short amount of time.

====Mistyped variable====
Typing ''chr_lod 4'' will produce this error: ''Func "(null)", File "(called from console)", Line 1: Illegal token, got "0" expected ";"''. That's because "chr_lod" is a variable and you need to use the equals symbol to set a variable. The correct use of this variable would be ''chr_lod = 4''.

====Mistyped function====
Typing ''killled_griffen = 1'' will produce ''Func "(null)", File "(called from console)", Line 1: semantic error, symbol "killed_griffen" is not a variable (function most likely)''. That's because "killed_griffen" is a function, and you simply list values (parameters) after function names, with no equals symbol. The correct use of this function is: ''killed_griffen 1''.

Another incorrect example: Typing ''chr_givepowerup = 0 ammo 1'' will produce:
: ''Func "(null)", File "(called from console)", Line 1: semantic error, symbole "chr_givepowerup" is not a variable (function most likely)''
: ''Func "(null)", File "(called from console)", Line 1: Illegal token, got "ammo" expected ";"''
The correct use of this function is ''chr_givepowerup 0 ammo 1''.

====BSL commands per file limitation====
The engine has some kind of limit on how many BSL commands can occur in a single BSL file. When you pass the limit, you'll get errors in the developer console like this: "Func "main", File "(called from engine)", Line 0: semantic error, function "main" does not exist." (it can also be a function other than "main").

For an example, extract these files and place them in IGMD/EnvWarehouse to experience the problem: [http://script10k.oni2.net/wikifiles/main_not_working_without_commenting_commands.zip], [http://script10k.oni2.net/wikifiles/main_not_working_without_commenting_commands(functions_splitted).zip], [http://script10k.oni2.net/wikifiles/main_splitted_in_two_files.zip]

In all these BSL files, the message "This message should appear on the beginning" should appear when you load level 1. However for "main_not_working_without_commenting_commands" it doesn't work unless you comment out the 5th line of the BSL file. The "main_not_working_without_commenting_commands(functions_split)" script is the same, but in this one the "main" function is split into two functions, which is still not enough for the error to go away. The scripts in "main_split_in_two_files" are the same BSL as previously, but the two functions are split into two different files: "main.bsl" and "continuation.bsl". In this case the script works as expected, and the message "This message should appear on the beginning" appears on level load.

So if you experience the error "Function "x" does not exist." when in fact it does, try spreading your functions across more BSL files and it should fix the problem.

==OniSplit error messages==
===TRAM-related===
* ''COLLADA error: duplicate id light'' - Maybe your DAE file has more than one root scene. In this case, you can right-click the model (which selects all 19 bones), then go to the Crosswalk settings, check "Selection Only", and save the file.
* ''.dae files cannot be imported as TRAM'' - Newer OniSplit versions doesn't seem to support "-create:tram" any longer. If you use that command, download an older version like v0.9.41.0 from Mod Depot.
* If TRAM*tgt has more than 256 (0-255) frames, you'll see:

Parametername: Value too large for Byte
at Oni.BinaryWriter.WriteByte(Int32 value)
at Oni.Totoro.AnimationDatWriter.WriteRotations(List`1 rotations, Int32 frameSize)
at Oni.Totoro.AnimationDatWriter.WriteAnimation()
at Oni.Xml.XmlImporter.ReadAnimation()
at Oni.Xml.XmlImporter.Import(String filePath, String outputDirPath)
at Oni.Program.ExecuteTasks(String[] args, String outputDirPath, Set`1 importedFiles, Queue`1 taskQueue)
at Oni.Program.CreateGeneric(String[] args)
at Oni.Program.Execute(String[] args)
at Oni.Program.Main(String[] args)

===TRBS===
In DAE files, if a bone has a point cluster, OniSplit v0.9.94.0 fails to convert the file.

==AE Installer==
===Blank mod list===
Your user account probably doesn't have the necessary rights that the AE Installer needs. In Windows, this can happen if you have Oni installed on an ''old'' hard drive which is now wired to your new system. Add "full control" to your account by right-clicking the Oni folder, choosing Properties, and going to the Security tab.

==XSI/Mod Tool errors==
===Corrupted DAE files===
Situation: ''I cannot load my DAE file into XSI. It give me an "Unspecified Failure".''

Possible cause: When you create the DAE file, there are file paths are stored inside it. If a path contains an illegal character, XSI cannot load the file.

Solution: Make sure the paths use only letters of the [[wikipedia:English_alphabet|English alphabet]].

===Object with test texture===
If the texture's file name contains a "#", ModTool fails to apply that texture and use its rainbow-colored test image instead.

[[Category:Modding tutorials]]

OniSplit

2025-01-22T18:50:25Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Commands -> Levels}}
{{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] ([https://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/Naming|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 [https://web.archive.org/web/20201127180431/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]]

SketchUp tutorials and tips

2025-01-22T18:47:29Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Tutorials}}

==Tutorials==
{| border=1 cellpadding=5
! Tutorial
! Author
! Link
! Status
! Notes
|-
| How to make a simple level
| [[User:Lukas Kreator|Lukas Kreator]]
| [https://web.archive.org/web/20190712222844/http://oni.bungie.org/forum/viewtopic.php?pid=35324 Oni Central Forum]
| Finished, but outdated
| Replaced by the tutorial below
|-
| Creating the Lair - A level tutorial
| [[User:EdT|EdT]]
| [https://web.archive.org/web/20201029114347/http://oni.bungie.org/forum/viewtopic.php?id=2087 Oni Central Forum]
| Finished
|
|}

==Tips==
([[User:EdT|EdT]]: You are welcome to put some tips here, about the doors and lasers for example...)

===Faces===
Faces are made when you draw a rectangle, a triangle or a polygon. For example, a cube has 6 faces, because it is made of 6 squares. You could also consider the faces inside the cube, if it is hollow. Faces with no textures show in SketchUp as white or blue. White means it is a "front face", blue means it is a "back face". Oni will not draw back faces, and you cannot collide with them. You can flip the faces using Right Click -> Invert Faces, after selecting one or more faces. I suggest that you first invert back faces, and then texture the level. In old versions of OniSplit, back faces have to be textured too, in order for the level to be converted to AKEV successfully.

===Stairs===
[[Image:Stairs with invisible ramp.png|thumb]]
If you want to make stairs, make the steps very small or make a ramp over it with an invisible texture. You can use [http://iritscen.oni2.net/wiki/Lukas%20Kreator-Invisible512px.png this all-transparent texture]. The stairs should then look like the image on the right.

===Rotating geometry===
Some things may be rotated when you try to load your level in Oni. This seems to happen when the user groups stuff together and forgets to ungroup them later. There are two ways to fix it:
* Load your level in XSI Tools and export the .dae from there. Does not work always.
* Try to find what is grouped and ungroup it.

===Yellow faces===
A weird phenomenon happened when an user from OCF (Delano762) was making a new level. There were yellow faces on some places. It is currently unknown what these are, but they seem to have been generated when he converted a Counter Strike map to a COLLADA .dae through a tool. According to him, he was unable to change the texture of these faces if he selected all faces in the level at the same time, but he could change them back to the default texture one at a time.

===Common errors===
* If your level was converted successfully by OniSplit, but when you try to play it, Oni crashes after about 10% of loading the level, this means there are textures in the model that were not included in the level folder. For example, the model uses TXMPtexture, but TXMPtexture.oni is missing from the level files.
* If you cannot convert your level to AKEV because OniSplit throws an error, you could be missing textures on some faces. Back faces also have to be textured, as far as I know.
** Note: This does not occur with the latest OniSplit, if a face does not have a texture, OniSplit will assign TXMPnotfoundtex to that face. So there is no need to assign textures to back faces. - [[User:EdT|EdT]]
* Sometimes OniSplit may throw an error similar to this: "Unsupported primitive type "<something>" found in geometry "mesh<number>-geometry", ignoring". I usually ignore this, because I don't know any case in wich this was a problem. Please, correct me if I'm wrong.

[[Category:Modding tutorials]]

Using the Rigify animation rig

2025-01-22T18:45:47Z

Vortice: Update notice w/ summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Required Tools and commands -> Brief overview on TRAMs.}}

==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.
* [https://web.archive.org/web/20211202215118/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.app/ '''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]]

Creating a level

2025-01-22T18:40:56Z

Vortice: Update Template w summary

{{update|This article contains links to the now defunct Oni Central Forum. Sections: Vertex Coloring -> Level-wide Shading, Links to Forum Tutorials}}
This page covers level creation from scratch. See [[Modifying an existing level]] if you want to change a vanilla level in the game.

==Level releases and resources==
===Fan-made levels===
{| class="wikitable sortable autosort by-column-3"
!Date
!Name
!Level number
|-
|TBA
|Oni 2 Angel Studios Tour
|32
|-
|TBA
|Green Room
|26
|-
|2019/09/16
|[https://web.archive.org/web/20240527004257/http://oniforum.bungie.org/viewtopic.php?id=2965 Omega Tournament]
|31
|-
|2016/02/13
|[https://web.archive.org/web/20160224173743/http://oni.bungie.org/forum/viewtopic.php?id=2947 AI Battle]
|7
|-
|2014/01/19
|[https://web.archive.org/web/20211202225410/http://oni.bungie.org/forum/viewtopic.php?id=2698 Wilderness Preserve]
|17
|-
|2013/09/07
|[https://web.archive.org/web/20201127180732/http://oni.bungie.org/forum/viewtopic.php?id=2656 Island]
|29
|-
|2013/07/12
|[https://web.archive.org/web/20201127175459/http://oni.bungie.org/forum/viewtopic.php?id=2640 City]
|28
|-
|2013/06/01
|[https://web.archive.org/web/20201029102326/http://oni.bungie.org/forum/viewtopic.php?id=2619 Fight Club]
|25
|-
|2012/05/12
|[https://web.archive.org/web/20220701102842/http://oni.bungie.org/forum/viewtopic.php?id=2357 Old China]
|24
|-
|2012/03/18
|[https://web.archive.org/web/20211202220454/http://oni.bungie.org/forum/viewtopic.php?id=2302 Boss Battle]
|23
|-
|2012/02/12
|[https://web.archive.org/web/20201029113554/http://oni.bungie.org/forum/viewtopic.php?id=2271 De Dust Deluxe]
|22
|-
|2012/01/23
|[https://web.archive.org/web/20201029114415/http://oni.bungie.org/forum/viewtopic.php?id=2242 Parkour Challenge 2]
|21
|-
|2012/01/16
|[https://web.archive.org/web/20211205145843/http://oni.bungie.org/forum/viewtopic.php?id=2235 Parkour Challenge]
|21
|-
|2011/07/25
|[https://web.archive.org/web/20201029103607/http://oni.bungie.org/forum/viewtopic.php?id=2001 Mini-Partenon]
|5
|-
|2011/10/03
|[https://web.archive.org/web/20201029113340/http://oni.bungie.org/forum/viewtopic.php?id=2024 Muro's Lair - Preview]
|20
|-
|2011/07/03
|[https://web.archive.org/web/20201029113724/http://oni.bungie.org/forum/viewtopic.php?id=1957 Hexagon]
|16
|-
|2011/06/23
|[https://web.archive.org/web/20201029104928/http://oni.bungie.org/forum/viewtopic.php?id=1938 Junkyard]
|15
|-
|2011/05/01
|[http://mods.oni2.net/node/178 Arena of Hurt (OZG)]
|7
|-
|2010/11/08
|[https://web.archive.org/web/20210117150652/http://oni.bungie.org/forum/viewtopic.php?id=1736 Arena of Hurt (OTA)]
|7
|-
|2010/11/06
|[https://web.archive.org/web/20201029105217/http://oni.bungie.org/forum/viewtopic.php?pid=50565#p50565 Martian Colony] AKA "Silly World"
|5
|-
|2010/02/15
|[https://web.archive.org/web/20201029113916/http://oni.bungie.org/forum/viewtopic.php?id=1506 Maze]
|5
|-
|2008/09/16
|[http://mods.oni2.net/node/4 Arena of Pain]
|30
|-
|2024/05/20
|[https://gamebanana.com/mods/514707 Kitsune: Chapter 1]
|20
|}

===Forum tutorials on level creation===
* '''[https://web.archive.org/web/20201029114347/http://oni.bungie.org/forum/viewtopic.php?id=2087 "Creating the Lair - A level tutorial"]'''
* [https://web.archive.org/web/20201127172559/http://oni.bungie.org/forum/viewtopic.php?pid=53026 "Creating a Custom Oni Level (s10k video tutorials)"]
* [https://web.archive.org/web/20201127180431/http://oni.bungie.org/forum/viewtopic.php?id=1515 "Creating new levels"]
* [https://web.archive.org/web/20201029114358/http://oni.bungie.org/forum/viewtopic.php?pid=33838 "Create levels with pathfinding grids"]
* [https://web.archive.org/web/20210117145338/http://oni.bungie.org/forum/viewtopic.php?id=2000 "More questions about levels"]
* [https://web.archive.org/web/20201029103906/http://oni.bungie.org/forum/viewtopic.php?pid=37252#p37252 "Modding Existing levels - Beta" ("Moveable furniture" post)]

===Wiki pages on level creation===
* [[Creating a level]] (you are here)
* [[Modifying an existing level]]
* [[New levels]]
* [[Lightmapping levels]]

===Free asset sources===
* [http://vk.com/gameready Various game meshes]
* [http://web.archive.org/web/20230601050258/http://tutorialsforblender3d.com/Textures/Textures_index.html Various game textures]
* [https://www.textures.com Various game textures]

==Engine limitations==
First you should be aware of the limitations that Oni will place on your level.

* The triangle limit of a game level is approx. 520,000 (consider it 500,000 to be on the safe side).
* {{ModTool}} can save DAE files with a maximum of 64,000 triangles per object.
* When polygons are too tightly packed, the camera will look at too many of them and glitches will appear. The limit on visible GQs (Gunk Quads) is 8,192 (213), and higher numbers will cause render bugs and produce the console error message "Exceeded max visible GQs ''number''". There are limited solutions to this:
** Decrease the '''gs_farclipplane_set''' value.
** Hide objects via '''[[#.3CModel.3E|env_show]]'''.
** Hide objects by ''level design''. For example, departments in a building could be quite detailed because the view of the other departments/rooms is blocked by walls.
* The camera can look at 2,049 transparent textures at once; one more, and Oni crashes.
* Characters are visible ''only'' within world coordinates {-4,099, -4,099, -4,099} to {4,099, 4,099, 4,099}.
* Geometry stops outside of (roughly) world coordinates -4,228 to 4,228 on the X and Z axes (vertical axis not tested).
* '''chr_debug_spheres = 1''' visualizes the collision spheres of characters, so you can check if they will fit through an entrance.

==3D tools==
===Problems when using multiple different tools===
Re-saving a DAE file in '''Mod Tool''' which was originally made in '''SketchUp''' can result in a surprising change in size within Oni. This is due to a difference in the specification of a scale unit.

: For example, the SketchUp DAE file may have: <tt><unit meter="0.0254000" name="inch" /></tt>
: And the re-saved Mod Tool DAE file may have: <tt><unit meter="0.1" name="decimetre"></unit></tt>

In that case you'll need to open the new DAE in a text editor and change the length specification back.

===Sketchup===
If you are working with Sketchup check out this pages:
* [http://oni.bungie.org/forum/viewtopic.php?id=2003 "Sketchup tutorials for making levels"]
* [[SketchUp tutorials and tips]]

===Blender===
'''Scaling'''

Same as Mod Tool and SketchUp: Caution with scaling: See [[#Problems when using multiple different tools|here]]

'''Pathfinding'''

Be sure to uncheck automatic triangle creation when exporting (BNV) geometry used for pathfinding. Ghost (''doors'') must be quads.

==Setting up a workflow==
If not noted differentely you need OniSplit v0.9.82.0 or a newer version. Onisplit can be downloaded [http://mods.oni2.net/node/38 HERE] (it also comes with the [[AE]] and is found in the Tools directory of the installation).

The level import demo files can be downloaded [http://mods.oni2.net/node/299 HERE].

First, put '''OniSplit.exe''' into the second '''lab''' folder alongside the XML files.

Look at the file '''build.cmd'''. These are the two important lines:

OniSplit.exe -create:level out lab.xml
OniSplit.exe -import:pc out level3_Final.dat

The first line creates the *.oni files from a master.xml file, in this case '''lab.xml'''. Once finalized, the resulting .oni files can be put into a new [[Making a mod package|AE package]].

The second line creates level archives which can be used for fast tests. They don't require you to install a package through the AE Installer.

Instead of "-nosep" you can now also use "-pc" for the import. Macs, however, do use "-sep".

==Troubleshooting==
If the game crashes while loading at ~90% progress, be sure that the texture's x and y dimensions are powers of two: 64, 128, 256, 512….

If the game crashes while loading at ~50-60% progress, be sure that the BINACJBOCharacters or AISA file has a player character defined.

If the game crashes while loading ~5-10% progress, check if all your textures were inside the "out" folder.

:You can extract the AKEV file to XML, then search for the [[XML:AKEV#TXMA|TXMP Array]].

:[http://mods.oni2.net/system/files/AKEV_texture_checker.txt THIS] script checks which textures are missing by comparing the AKEV*.xml with its *.oni files folder. Change the two paths so that it works for you: Alt+4, insert code, then F5.

"TXMP_marker_door" and "TXMP_marker_ghost" will be missing in the demo's "out" folder.

You can add this between the other two lines in build.cmd to prevent a crash.
OniSplit.exe -create:txmp out env/markers/*.tga

==Terminology==
;Polygon
:A polygon is a shape defined by points (vertices) in space. Polygons are the most fundamental building block in games. Oni uses only shapes with 3 and 4 points (triangles and quads). Other games might also use N-gons, shapes with more points.
;Face
:The '''surface of a polygon''' is also named face. The '''direction''' of a face in '''defined by its normal'''. If an object seems to have a hole, it might be that the polygon just has a '''flipped normal''' and is therefore wrongly rendered (displayed on screen).
;Normal
:Faces and even vertices themselves have directions. The normals of vertices determine how smooth or sharp edges will appear.
;Vertex (plural<nowiki>:</nowiki> vertices)
:A point within a polygon.
:Vertex colors radiate from one vertex to another vertex, whereby their different color values blend into each other so that gradients can appear.
;Edge
:A line of two points within a polygon.
;Tris (triangles)
:Polygons made of 3 points.
;Quads
:Polygons made of 4 points. Planes. Rectangles.
:Internally, all quads get converted into two triangles and will affect the maximum triangle count accordingly.
;Level
:The term "level" is often used to shorten "level map" (buildings and terrain).
;Geometry
:Level geometry can be objects made of tris and/or quads.
:Oni differentiates between basically 3 types of level geometry:
:* Static objects (sometimes also named AKEV core geometry)
:* Animated objects
:* Pushable objects (not used in the original game)
;Static geometry
:* '''Unique level geometry with no functions''' (AKEV core geometry such as buildings and streets).
:* '''Repeating objects''' are flagged as '''furniture (FURN)''' although they can be outdoor objects such as boxes and containers. FURN objects were used to be imported by an object collection, an CJBO. Nowadays, furniture collections can be used (again) for imports, but the individual objects are stored as OFGA files. This modularity is known in many game editors (like the Unreal Engine Editor). So, '''OFGA are nothing else than "game assets".''' The drawback of OFGA is that they '''will not import with any vertex shading'''. Only their '''geometries''', attached '''particle''' and '''gunk flags''' get copied into final (baked) level geometry.
:* '''Objects with actual functions''' (CJBO such as doors, consoles, triggers)
:** Some types of CJBO (spawn lists of weapons, characters, powerups and of course flags and patrol paths) are not considered as level geometry.
;[[XML:AKEV#AGQG|Gunk flags]]
:Properties directly associated with the polygons. Among others, these can be: Transparent, TwoSided, NoCollision, Invisible, NoObjectCollision, NoCharacterCollision, NoDecals, Furniture, Impassable.
;Baking
:When a level gets baked, all geometries get merged.
:*Unique level geometry will have vertex painting.
:*Objects derived from already compiled oni-files (shared classes) will have no vertex painting.
:*Animated and pushable objects will have no vertex shading.
;Vertex shading
:Vertex colors (vector data) can be painted onto core geometry.
:They are used as a rudimentary form of lightmapping (pixel data).
:Having vertex shading is still better than having no vertex shading at all. It makes the level appear more lifelike.
;Lightmapping
:In other games, lights and shadows are added to level geometry with lightmapping.
:There were experiments to bring lightmaps back to Oni. The technique come with a major drawback though. It doubles the triangle count and adds many textures.
;In-game
:When you are "inside" the game, running or playing it.

==Level construction==
'''Visible environment'''
* A '''level map''' consists of visible geometry: terrain and buildings. This is also named the '''environment''' or for short '''env'''.
** Use '''quads''' of approximately 10 up to 20 meters in size to construct env geometry.
* Anything other than floors and simple walls will be made of triangles.
** Geometry from CJBO works best with triangles. Quads might show holes in-game.
'''Invisible pathfinding'''
* '''AIs''' (or non-player characters, NPCs) need '''pathfinding''' data, usually shortened as '''bnv'''.
** Pathfinding data can be described as geometry, therefore as rooms. These '''bnv rooms''' are made of '''floors''' and are connected by '''ghost''' quads which work like doors. AIs can move from one room to another room only by passing a ghost. Therefore, ghosts have the same width as rooms in open terrain.
*** Use floor quads of approximately 10 meters in size to construct BNV floors.
*** Put ghost quads exactly on the edges of BNV floors with an angle of 90 degree.
'''Support for [[XML:BINA/ONIE|effects]]'''
* Effects such as decals that indicate damaged environment need level textures to be registered in [[XML:BINA/TMBD|TMBD]]. Make sure not to replace existing texture entries but to add your own so that the other levels remain unaffected.
'''Level logic'''

BSL scripts bring levels fully to life. The logic is mostly event driven whereby different checkpoints and conditions must be reached.
* Checkpoints are actually [[XML:BINA/OBJC/TRGV|trigger volumes]] that can recognize entering and exiting characters.
* The second most important source of events are [[XML:BINA/OBJC/CHAR|character (script) functions]], especially the die function of enemies.
** To support good and less good players alike, NPC characters can feature the UpgradeDifficulty flag. Also, BSL scripts can detect the current [[BSL:Game_status|difficulty level]].
* [[XML:BINA/OBJC/TRIG|Laser triggers]] are mostly used to control [[XML:BINA/OBJC/TURR|turrets]]. [[XML:BINA/OBJC/CONS|Consoles]], triggers and [[XML:DOOR|door]] unlocking are used to set up very simple "riddles”.
* The creation of cut scenes is time-consuming quality work. Due to missing tools for streamlined workflows, it is totally okay for you to skip this.
** New synchronized FILM, OBAN and TRAM files are required for cut scenes. Not to mention sound files for dialog.

==The master XML file==
''The project file for level creation.''

The '''master XML''' file's '''name determines''' the '''BSL folder name''' and the '''AKEV and ONLV file names''' in the output folder. File paths in the XML can be either absolute or relative.

'''Mandatory files''' for level import:
* ''level_environment''.dae
* ''level_bnv''.dae
* ''level_textures.tga/jpg/png''
* Character.xml or AISA with player
* ONSK name in <Sky> (in Windows, this can be a fake name; does the Mac need actual ONSK files?)
* ONLD file for the new level; read [[Making_a_mod_package#Mod_Info.cfg|HERE]] about making sure your level is unlocked (accessible on the Load Game screen)

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
|valign="top"| <Level SharedPath="...">
|valign="top"| link
| The master XML file can link to other XML files. Most of them will be [[OBD:BINA/OBJC#OBJC_types|BINACJBO]] files. The file type is declared inside the file, so the file name itself doesn't have to contain the type. Ergo, "BINACJBOCharacter.xml" can be given a simpler name like "Character.xml".

Some resources used by those XML files can be found in a '''shared''' folder. OniSplit copies textures and "physics" objects into the output folder; furniture objects will be integrated into the AKEV. Unused resources in the shared folder will be ignored. That way the final level archive or AE package contains only the necessary files, saving disk space for the end user.

In the demo are various subfolders in the '''shared''' folder: consoles, doors, furniture, triggers and turrets. These file types do not need their file prefixes: CONS, DOOR, TRIG and OFGA. OniSplit will recognize them nonetheless.

'''Common mistake:'''

CJBO files '''need relative paths to the resource instead of just file names'''. Taking consoles, for example: a standard export to XML gives you "console_data". But to use the shared resources these must be paths like "'''consoles/console_data.oni'''" as they are stored in '''shared/console/'''. Note how the demoed '''shared''' folder is placed next to the [http://mods.oni2.net/node/299 project ("lab")] folder and the XML master file points to it using "../shared".
|-
| <Environment>
| -
|
|-
| <Model>
| -
| Used to import level geometry and static objects. See [[#<Model>|HERE]] for detailed information.
|-
| <Import Path="..."/>
| link
|
|-
| <Node Id="...">
| string
| informational (space for notes)
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Can be used with BSL commands such as ...
: [[#<Model>|env_show ID 1]] (use 0 to hide)
: [[#Breakable glass with BSL recognition|env_broken ID1 [ID2]]] (if a second ID is supplied then objects in the range ID1..ID2 get counted; "3001 3018" would cover 18 objects)
: [[#Texture exchange|env_texswap ID texture]] (no file prefix/suffix allowed)
: [[#env_shade|env_shade ID ID R G B]]
Static objects store their ID in [[XML:AKEV#IDXA_.28quad_group_id.29|one of AKEV's IDXA instances]].
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
|valign="top"| <Rooms>
|valign="top"| -
| For detailed information see [[#<Rooms>|HERE]].

For a Google SketchUp BNV tutorial see [http://oni.bungie.org/forum/viewtopic.php?pid=36760#p36760 HERE].
|-
| <Import Path="..."/>
| link
| File path to *.dae file. BNV data, used to create pathfinding.
|-
| <Textures> {{Anchor|textures_tag}}
| -
| With OniSplit v0.9.94.0+ you can use attributes to set the default import formats and max dimensions. For example:

: <Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">

Textures with a dimension that isn't a power of two (2x) and textures larger than 512px on a side will be resized. For example, 2003x2000 will become 512x512. (What would 257x255 become?)
|-
| <Texture Name="...">
| string
| TXMP file name to generate.
|-
| <Flags>
| flag
| Optional tag. For list of flags see [[XML:TXMP|HERE]].
|-
|valign="top"| <Format>
|valign="top"| flag
|
:DXT1
:BGR
:RGBA
:BGR555
:BGRA5551
:BGRA4444
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
| <Image>
| link
| File path to *.tga/jpg file.
|-
|valign="top"| <Sky>
|valign="top"| string
| ONSKfile.oni (without file pre- and suffix)

The import doesn't work with an empty tag. <Sky>clear</Sky> helps here; any other fictional name will also do.

For detailed information see [[XML:ONSK|HERE]].
|-
| <Objects>
| -
|
|-
|valign="top"| <Import>
|valign="top"| link
| File path to an OBJC (collection) file. Supported collection files for <Import> are:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[#Furniture.xml|Furniture.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[#Physics.xml|Physics.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

The following two collection files are '''NOT''' supported. You need to copy them as regular pre-compiled *.oni files into your mod package:
: [[XML:BINA/OBJC/MELE|Melee.xml]] (overrides global MELE; not used in vanilla levels)
: [[XML:BINA/OBJC/CMBT|Combat.xml]] (overrides global CMBT?; not used in vanilla levels)

'''Inside''' the following three supported collection files, provide links to pre-compiled (*.oni) class files: console, door and furniture collections. Use relative paths such as:
:: <code>'''consoles/'''console_data'''.oni'''</code>
:: <code>'''doors/'''TCdouble'''.oni'''</code>
:: <code>'''furniture/'''V_tctf_bigvan'''.oni'''</code>

When you are unsure about the folder structure refer back to the [http://mods.oni2.net/node/299 level import demo].
|-
| <Films>
| -
|
|-
| <Import>
| link
| File path to *.xml file. OniSplit creates a [[XML:FILM|FILM]] file from it. Used for characters in cutscenes.
|-
| <Cameras>
| -
|
|-
| <Camera Path="...">
| link
| File path to *.dae file. OniSplit creates an OBAN file from it. Used for cutscenes.
|-
| <Animation Name="..."/>
| string
| Name for the OBAN file.
|}

This is a trimmed-down version of the master file '''lab.xml''' from the demo. It's meant to give you a first impression. We might upload a smaller demo someday with all features nonetheless.

<?xml version="1.0" encoding="utf-8" ?>
<Oni>
<Level SharedPath="../shared">
<Environment>
<Model>
<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_bomber_window.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>
</Model>
<Rooms>
<Import Path="env/lab_bnv.dae"/>
</Rooms>
<Textures>
<Texture Name="GOO">
<Format>bgra4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>
</Environment>
<Sky>sunset</Sky>
<Objects>
<Import>Character.xml</Import>
<Import>Furniture.xml</Import>
<Import>TriggerVolume.xml</Import>
<Import>Physics.xml</Import>
</Objects>
<Films>
<Import>films/BomberKonRun01.xml</Import>
<Import>films/BomberKonRun02.xml</Import>
</Films>
<Cameras>
<Camera Path="cameras/BomberCam01.dae">
<Animation Name="BomberCam01"/>
</Camera>
<Camera Path="cameras/BomberCam02.dae">
<Animation Name="BomberCam02"/>
</Camera>
</Cameras>
</Level>
</Oni>

===<Model>===
This tag is mandatory (it must be present to avoid errors); the model section contains one import path to the AKEV (level) geometry (*.dae) and can contain additional import paths for exceptions (*.dae).

Data from the demo:

<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>

'''env_show'''

The motorcycle has here scripting ID 9. You can show and hide the object with the BSL command '''env_show''', where the second parameter means true or false. '''Never use 0 as an ID''' because it won't work.

env_show 9 1
env_show 9 0

EdT demonstrates env_show [https://www.youtube.com/watch?v=Em6wa5JTQNM here]. Note how the objects have collision.

The last vanilla level (Syndicate Mountain Compound) has a big satellite dish platform that can be made hidden. Obviously, such objects/areas can be made to have pathfinding too.

;More possible applications of env_show:
* ground/ceiling/objects for cutscenes that become partially destroyed
* destructible walls like in Deus Ex: Human Revolution (trigger volume, replacing punch anim with punch-through-wall anim)
* grids in front of ventilation shafts (a small door object could be an alternative)
** at the moment this can't be done because characters can't sneak under the top edge of the opening (the characters collision spheres are too big)
* managing object groups with trigger volumes (save multiple objects in one DAE file)



====Import of object groups====
'''Mod Tool versus SketchUp'''

The meaning and behavior of "groups" greatly differs in these two programs.

:'''In SketchUp''' you can group objects which enables you to easily duplicate all objects inside a group and to scale/rotate/translate them all together.

:'''In Mod Tool''' grouped objects are still loose, and duplicating a group won't duplicate the objects. To achieve the same effect as in SketchUp, you have to create a hierarchy where any one object is the "parent" and all others the "children".

'''Google SketchUp'''

To create a group, select two or more objects, right-click on the selection and choose "make group".

[[Image:ModTool_can_import_objs_in_hierarchies.jpg|right|thumb|Mod Tool can import objects in hierarchies to Oni.]]
'''Mod Tool'''

Either use the Explorer (A) or the Schematics (B) to create a hierarchy.

:(A) In the Explorer window, drag and drop one or more objects onto another one.

:(B) Open the constrain tab at the right side. Select parent object, click "Parent", click the child object(s). Check the result in the Schematics window.

:'''Mod Tool: caution when saving to DAE!'''

:A normal selection won't do. You have to select the object tree to successfully save a hierarchy. This is the same way that you do it with Oni characters.


====Breakable glass with BSL recognition====
Broken environmental objects can be recognized by the BSL command ''env_broken (ID_1, ID_N)''. However, this requires additional code to work.

An example is the training level. Let's determine how we can set up such a thing.

First we need a [[XML:BINA/OBJC/TRGV|trigger volume]] like in level 1.

<TRGV Id="11495">
<Header>
<Flags>Locked</Flags>
<Position>-714.6615 -298 -555.2073</Position>
<Rotation>0 0 0</Rotation>
</Header>
<OSD>
<Name>tv75</Name>
<Scripts>
<Entry></Entry>
<Inside>targets_gone</Inside>
<Exit></Exit>
</Scripts>
<Teams>255</Teams>
<Size>400 31 270</Size>
<TriggerVolumeId>75</TriggerVolumeId>
<ParentId>0</ParentId>
<Notes></Notes>
<Flags>PlayerOnly</Flags>
</OSD>
</TRGV>

Now we need some BSL code.

var int inside_target_function;

func void enter_target_function(void)
{
dprint enter_target_function
inside_target_function = 1;
}

func void exit_target_function(void)
{
dprint exit_target_function
inside_target_function = 0;
}

func void targets_are_not_gone(void)
{
# CB: turn off the trigger volume and sleep for a second
# so as not to cause hideous performance loss
trigvolume_enable tv75 0
sleep 60
trigvolume_enable tv75 1
}

func void targets_gone(string ai_name)
{
if (inside_target_function eq 0)
{
enter_target_function() # catch other "targets_gone" functions to let them do nothing

var int num_broken = env_broken(3001, 3018);
# if you only one target use scheme: env_broke(3001, 3001)

if (num_broken eq 18)
{
targets_are_gone();
}

if (num_broken < 18)
{
targets_are_not_gone(); # to set check interval to one second
}

exit_target_function
}
}

func targets_are_gone
{
trigvolume_enable tv75 0
# [...]
}

;Explanation:

Player enters the TV, targets_gone() gets triggered. The variable "inside_target_function" should be 0 by default, so we will enter the "if" block. Next, we can assume that the player didn't destroy all glass objects, so "num_broken" will be less than 18; thus, targets_are_not_gone() gets called.

The TV function targets_gone() ''would'' be triggered every frame, but targets_are_not_gone() creates a delay between checks: the TV gets deactivated for 60 frames. Then the TV becomes enabled again and will start anew until all glass objects got destroyed or player left the TV.

In this case the targets_gone() function will do nothing because "inside_target_function" was set to 1 by the first call.

targets_are_gone() eventually disables the TV to prevent memory overflow; this function also contains all the things ("[...]") that you want to happen after the glass target is broken.

====Texture exchange====
BSL command supported on Windows and Mac:
: env_texswap ID texture

Might be useful to switch on/off static and animated textures. (News broadcast screen: running or off or smashed. Lava stream: flowing or stagnating or cooled down. Etc.)

A similar effect can be achieved by showing/hiding geometries with different textures as EdT has demonstrated in a private test. That way it should also be possible to have different vertex coloring for an area.

====Vertex coloring====
Vertex colors can be edited manually in Blender by setting up following 3 things:
* Properties Panel > Data > Color Attributes
* 3D viewport (left top) > change work mode to Vertex Paint
* 3D viewport (right top) > change to Viewport Shading to Solid mode (under the dropdown menu you can choose "flat" to have full saturation)

{{divhide|Mod Tool}}

[http://web.archive.org/web/20170529111607/http://softimage.wiki.softimage.com/xsidocs/tex_vcolor_CreatingColoratVerticesCAVMaps.htm SoftImage documentation.] Observation: The sniper tower from level 19 Syndicate Mountain Compound can be isolated and re-imported as it is. It will appear quite dark.

If we remove "_color" from the object, the shadows will be gone next time we import the tower.

Mod Tool: Explorer [8]

Object
|
+-- Polygon Mesh
|
+-- Cluster
|
+-- Polygon
| |
| +-- [...]
|
+-- NodeProperties
|
+-- '''_color'''
+-- texcoord (Explicit UVWs)
|
+-- Vertex_Color_Def

So, how do we modify that data?

'''Single object shading'''

If there's already a vertex color property, you can use Shift + W to activate the Paint Vertex Color Tool. With Control + W you can change the brush color. R + Hold Click + Move Mouse let you change the brush size. The more vertices (points) you have, the more detailed you can make the shadows/colors. But keep in mind that too many polygons can destroy collision, making characters fall through the ground.

If there's no vertex color property, the first usage of Shift + W will create that property. But you can also manually create it via Property > Color under Vertices Map.

'''Level-wide shading'''

[[Image:light_test_modtool.png|right|thumb]]
[[Image:light_test_ingame.png|right|thumb]]

To get general shading/lighting you can set up light sources. "Infinite" lights are useful for global lighting, while "Light Box", "Point", "Neon" and "Spot" are more suitable as local light sources. They can be accessed via Primitives > Light.

By default, a Mod Tool scene has one Infinite light, but it doesn't shine in every direction so you might want to add more Infinite lights. Let's say one Infinite light for each direction (+X, -X, +Y, -Y, +Z, -Z) with an intensity of circa 0.25 (night) or 0.75 (day).

The illumination of those lights can be integrated into the vertex color property. There's some information [https://web.archive.org/web/20201029114108/http://oni.bungie.org/forum/viewtopic.php?pid=29089#p29089 on OCF here]; the quoted information is in triplicate, so don't get confused by that: at first it's detailed, then summarized, then as a checklist.

Basically, you can go with the checklist:

* Property > Color At Vertices Map
* Property > Render Map
* In render map property page, under Sampling select Vertices Only
* Under Surface Color, choose Enable, then in the box below select Vertex _Color; if that option does not appear, click on the New button next to it
* Under Map, select Illumination only
* Finally, click on the button Regenerate Maps...

This must be done for all objects separately.

: [http://mods.oni2.net/system/files/vertex_color_script.txt There's a script here] which can apply vertex color and render maps to all '''selected''' objects. Load it into the script editor with Alt + 4 and hit F5 to run it. (Be sure the script's language was set to VBScript.)
: The variable "overwrite_VC" can be changed.
:: With "1" all existing CAV maps of selected objects will be overwritten. This can take some time.
:: With "0" only selected objects without CAV maps will be the script's target.

'''Notes on ModTool view modes'''
* "Constant" let you see the colors of the vertex coloring only.
* "Textured Decal" let you see object textures only.
* "Shaded" let you see the illumination only.
* "Textured" let you see the textured object with illumination and vertex coloring.
{{divhide|end}}

=====env_shade=====
If you use '''env_shade''', use it with caution. It completely overwrites the vertex coloring.

# BSL command
# env_shade obj_id obj_id R G B

# examples
env_shade 7 7 # object 7 will be black
env_shade 7 7 0 0 0 # object 7 will be black
env_shade 7 7 .31 .999 .5 # object 7 will be quite green
env_shade 7 10 1 1 1 # object 7, 8, 9, 10 lose all their shading

====Baked lightmaps====
A drawback of this method, AKA shadow maps, is the high number of [[XML:BINA/TMBD|TMBD]] changes and new textures for every wall, requiring a lot of memory. How to create shadow maps:

* https://web.archive.org/web/20121105081823/http://www.game-artist.net/forums/support-tech-discussion/5622-burning-shadows-onto-texture-xsi.html


Notes on map options:
* "Surface color and illumination": outputs used texture with added shadows
** Can be used to replace original texture
* "Illumination only": output a texture that only contains the shadows
** Can be used on a new overlying, transparent surface

====Standalone lightmaps====
With this approach there are two meshes, whereby the shadow effects on one mesh get drawn in front of the regular level texture.

Compared to the "baked lightmaps" method, this needs more polygons of course. And these polygons are transparent, which is a problem with Oni's limited rendering ability for such textures. However, standalone lightmaps only need a few new textures if used wisely.

Read [[Lightmapping levels]] to learn more.

[[Image:Oni_Lightmaps_double_polygon_method.jpg|center]]

===<Rooms>===
The Rooms tag is mandatory. It contains an import path to BNV and ghosts (*.dae) which are used to create pathfinding grids. For information on the binary data behind this, see [[OBD:AKVA|HERE]].

Sample code from the master XML file:
<Import Path="env/lab_bnv.dae"/>

'''Fundamentals'''
* '''BNVs''' are '''volumes''' (sometimes also named '''rooms''') that have a pathfinding grid assigned to them.
* For practical reasons you only need '''floors and ramps''' to build a BNV. (As seen [http://edt.oni2.net/images/Hideout_BNV.jpg HERE.])
** A BNV polygon can consist of 3 or more points, but it's recommended to use '''shapes with 4 points''' because the other shapes usually waste more grid space. At the moment you can import only '''[[wikt:convex|convex]]''' shapes.
* Secondly, there are so called '''ghosts''' (vertical quads) that connect '''neighboring BNVs'''. AI can only transit from BNV to another through ghosts.
: OniSplit gives error messages for ghosts that don't have 2 neighboring BNVs, for example:
BNV Builder: Ghost 'grid2' has no adjacencies at <-72,41 1,999 -166,6> and <-71 1,999 -168,21>, ignoring

'''Tolerance values'''
* Horizontal distance from room to ghost: 1
* Vertical distance from room to ghost: 18
* Ghost's horizontal dimension must be greater than 0
* Under optimal circumstances, pathfinding works on a plane that is +4 world units above or -0.5 below the pathfinding grid
* Normally characters can't pass over low vertical walls such as stairs/curbs if those don't have a ramp under them; near ground level (Y=0) is an exception where characters are allowed to step on a plane that is 4 world units above pathfinding grid; higher planes need a ramp
* Maximum angle of ramp you can go on is 70°; higher angles will make characters fall through to their death (in those cases you might want to add invisible walls/boxes to prevent them from touching the ramp)

'''More notes on PF processing'''
* Actually, BNV and ghosts can have any name and don't need any texture.
* During pathfinding calculation, OniSplit creates a new folder called "temp" and a subfolder "grids". There is a file named "''levelname''_grids.dae". That file contains rooms with textures called "bnv_grid_''N''.tga" which mark obstacles in the pathfinding grid. Ghosts will have a transparent texture "'''_marker_ghost'''.tga". You also get these when you export a level. Transparent ghosts make it easier to see the rest of your level if you have many of those planes.
* In Mod Tool, ghosts and rooms can be grouped under a null object. Right-click the null object to select all its children, then use "Selection Only [x]" as your saving option. That way all the planes can be quickly saved to a *.dae file.
* You can influence the pathfinding creation of dangerous zones using danger quads. Read about those [[#Marker textures|HERE]].
* Another kind of influence is the [[#<Model>|gunk flag]] IgnoreGrid. It can be used to tell OniSplit to ignore the object during pathfinding creation. The grids in that place will be white.

[[Image:Pathfinding_grid.jpg|thumb|200px|right|'''ai2_showgrids = 1''' in action]]
'''BSL commands'''
* chr_show_bnv = 1
:: shows number of BNVs the player is standing on
* ai2_showgrids = 1
:: shows pathfinding grids
* ai2_chump
:: spawns a friendly Striker that follows the player if possible, makes also pathfinding grids visible
* ai2_chump_stop = 1
:: Striker stops following you
* ai2_chump_stop = 0
:: Striker follows you again

====Pathfinding on uneven ground====
Pathfinding works on slightly uneven ground as long as the polygons are 0.5 world units beneath or 4 world units above the BNV.

For greater surface irregularities, we can use a trick:
* The problematic polygons must be saved to a DAE file and then referenced in the model section as an individual object.
* Then the <GunkFlags> tag needs to be '''''GridIgnore'''''.
* Additionally we create a plane (invisible if necessary) under the object so that Oni doesn't think there's a hole.
* The ghosts must be taller than the highest polygon to be walked on. (This has been tested up to a height of 2,000 world units.)

'''Symptoms of too-small ghosts'''

A) AI can't run at all.

B) AI loses PF ability if the tracked enemy performs animations that are outside of the pathfinding volume. Here's a video (<nowiki>https://youtu.be/vfKPzP5hiCo</nowiki>, dead link) showing these symptoms.

'''Missing boundaries'''

Let's say you have a BNV, tall ghosts, and a GridIgnore-flagged hill with trees and bushes and stuff.

Why do AIs run up against the trees?
: '''Problem:''' There are no red/orange grids that limit the AI's movement. Normally, objects will produce red pathfinding squares around them. But objects that are 20 world units above the BNV are ignored just like objects with the IgnoreGrid flag.
: '''Solution:''' Add simple geometries like ''_marker_impassable fences'' or danger quads near the BNV.

'''Disappearing AIs'''

The ground is sometimes not solid, and the player and AIs are falling through it.

: '''Problem:''' On GridIgnore-flagged uneven ground, AIs can fall through it when they are out of the player's view.
: '''Solution:''' Use either '''chr_lock_active ''AI_name''''' or '''chr_all_active = 1'''

====Debugging====
'''(OniSplit v0.9.93.0+)'''
[[Image:OniBrowser.jpg|thumb|200px|right|OniBrowser displaying level geometry plus PF and ghosts.]]

* '''env_show_ghostgqs = 1''' makes the ghost quads visible
** The original ghost quads can't be seen; per Neo, "they are not included in the octtree and bsp tree"
** To see them you must use the -debug option in the level creation command (available with OniSplit '''v0.9.93.0+''')
OniSplit.exe -create:level ''output_folder'' '''-debug''' ''input_folder''/''master_xml_file''.xml

Not all debugging/testing needs to be done in Oni. There is also a [http://mods.oni2.net/node/256 program] (Windows only) which can display the whole level.

For example you can load an AKEV*.oni, select the level name, and use the hotkeys [B] and [P] to display BNVs and ghosts.

'''Bug prevention:'''

After all testing is done, you should compile the level a last time without the -debug option.

AIs appear to have trouble shooting through ghost quads that got registered in the octtree/BSP tree as seen here (<nowiki>https://www.youtube.com/watch?v=-ZugVBgBVKc</nowiki>, dead link).

====When OniSplit fails to connect PF quads====
[[Image:Pathfinding_creation__merge_polygons_to_fix_connections.jpg|thumb|200px|right|Fixed PF in compound level after underground construction...]]
It can help to merge polygons to one object and merge their edges. These become white. (Outer edges are blue.)

===<Textures>===
====...used for exceptions====
The [[#textures_tag|textures tag]] is mandatory.

AKEV textures will be imported by the master XML file automatically; you don't need to add them to that file.

: With OniSplit v0.9.82-93.0, the textures' formats will be DXT1 and (for transparent ones) BGRA4444.
: With OniSplit v0.9.94.0+ the textures' formats will be BGR and (for transparent ones) RGBA.

To change the default texture import format, use the Texture'''s''' tag. (Possible with OniSplit v0.9.94.0+.)

To change the format/flag/gunk flag of a specific texture, use the Texture tag.

An example:

<Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">
<Texture Name="GOO">
<Flags>TwoSided</Flags>
<Format>BGRA4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>

* Use the gunk flag "TwoSided" to make surfaces visible from both sides.
* If the texture comes with the gunk flag "NoCollision" then all objects with that texture will have no collision. Characters would fall through it.

Transparency and no collision together would make sense for a water-like substance. The Vago Biotech level uses this approach for the area with green toxic waste.

[[Image:making_a_surface_transparent_and_twosided.png|thumb|200px|right|'''Figure 1''']]

[[Image:AKEV_single_object_multiple_textures.png|thumb|200px|right|'''Figure 2''' one object with multiple textures, one per polygon cluster]]
[[Image:AKEV_single_object_multiple_textures_ingame.png|thumb|200px|right|'''Figure 3''' blue: two-sided glass: two-sided and transparent random metal: no flag (one-sided)]]

'''TwoSided and transparent objects'''

It's also possible to set this in Mod Tool. For TwoSided-ness, use one image source for diffuse and transparency. (It won't work with two image sources even if both sources use the same image.)

For transparency you must additionally use the three checkboxes:
* Transparency: Enable
* Transparency: Use Alpha
* Transparency: Invert

See '''Figure 1'''.

====Regular textures====
OniSplit automatically imports textures of objects in the [[#<Model>|<Model> section]]. Those objects could be considered as AKEV core geometry.

'''One texture per object'''

Furniture and Physics objects are allowed to have only one texture per object. AKEV core geometry can have one texture or multiple textures – that's up to you to decide.

'''Multiple textures per object'''

'''Question:''' How do we apply multiple textures to an AKEV core object?

'''Answer:''' Assuming you are using Mod Tool the procedure will be as follows. Repeat this for each cluster you create (except for projection). See also '''Figure 2 and 3'''.

* Select some polygons
* Go to Material > Phong
* Hit [7] to open Render Tree
* Add a texture and connect "Image" with "Phong", choose "diffuse" as illumination mode
* Double-click "Image" to open Material page
* In the Texture Projection section, click on "New" and choose a suitable projection
** Do this only if there isn't a projection in the "Texture_Coordinates_AUTO" cluster yet
** OniSplit processes only one texture projection, see '''Figure 4'''
* Choose the texture and UV, then fine-tune the UV via Alt + 7

[[Image:AKEV_multiple_textures_one_projection.png|thumb|200px|right|'''Figure 4''' use only one texture projection per object]]

Caution: textures will be fixed to one set of flags. You can't use the same texture A for a one-sided cluster/object B and a two-sided cluster/object C. You would need to create a differently-named clone of that texture and apply that to cluster/object C.

====Marker textures====
Marker textures are used to import certain objects with special flags. Import those objects alongside [[#<Model>|AKEV core]] geometry.

Marker textures aren't imported automatically. Add those textures to the final package or plugin yourself, e.g. with some sort of script.

OniSplit.exe -create:txmp out env/markers/*.tga

The flags Transparent, TwoSided and NoOcclusion are only set if the same texture source is used for diffuse and transparency and if transparency setting are enabled. See the subsection under "[[#...used for exceptions|...used for exceptions]]" called "TwoSided and transparent objects".

'''Danger quads'''

Pathfinding grids have different colored squares with different meanings.
* white/gray - clear space
* green light - near wall
* green - semi-passable
* green dark - stairs
* blue very light - border 1
* blue light - border 2
* blue - border 3
* blue dark - border 4
* '''orange - danger'''
* red - impassable

For detailed information on colors, see [[OBD_talk:AKVA/0x24#EFFECTS_of_various_pathfinding_grid_tile_types|HERE]].

Normally, OniSplit decide how to color the grids. But it's possible to add your own danger quads to fine-tune zones of higher danger. Those orange areas will be generated with the 4 different blue borders around it.

Danger quads must have "'''_marker_danger'''" as texture name.

Results in flags: Transparent TwoSided NoCollision Invisible NoOcclusion Danger

'''_marker_barrier'''


Results in flags: Transparent TwoSided(double-check) Invisible NoObjectCollision NoOcclusion

'''COLLISION (boxes)'''

AIs can get stuck in detailed geometry. This can be prevented with collision boxes. In-game the box will be invisible, but has collision so characters can't get through. The pathfinding grid will be red where it comes in contact with the box; the red is followed by a light green and then regular green.

[[XML:OFGA|OFGAs]] use the COLLISION texture. Onisplit doesn't automatically apply gunk flags to it. You need to use XML tags for that. Typically it would be <GunkFlags>Invisible NoObjectCollision</GunkFlags>

'''Stairs'''

Texture: '''_marker_stairs'''

Normally, characters can't move on stairs because they contain vertical rises. In this case you can use a sloping quad that is above or inside the staircases. It's possible to set the desired flags in the <Model> section, but doing so and exporting these self-made stair ramps is wasted time. Simply apply _marker_stairs to that quad and characters will be able to move on that surface.

Resulting flags: Stairs Transparent TwoSided Invisible NoObjectCollision NoOcclusion

This has no effect on pathfinding creation. Regularly-textured stair geometry (which intersects the marker quad) will be flagged as NoCharacterCollision.

'''Impassable'''

texture: '''_marker_impassable'''

Resulting flags: Transparent TwoSided (<-double-check this) Invisible NoOcclusion

Impassable walls are very similar to collision boxes except that particles can also collide with them. The pathfinding grids will be also red, light green, and green.

'''Blackness a.k.a. jello fix'''

Texture: '''_marker_blackness'''

Resulting flags: TwoSided NoCollision

Simply black walls. No effect on pathfinding creation. The purpose of these walls in Oni is to block out areas outside of a level's outermost wall so that the Jello-cam cannot show the player other parts of the level when it escapes a wall. See [[Jello-cam]] for details.

'''Doors'''

Texture: '''_marker_door'''

Resulting flags: DoorFrame Transparent TwoSided NoCollision NoOcclusion

Don't use this.

===<Objects>===
Information on regular object lists can be looked up here:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

====Furniture.xml====
The AKEV core geometry is more or less the overall structure of the level while this furniture file adds standard objects (e.g. crates and desks) to it.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Objects>
| -
| This tag marks the file as BINACJBO.
|-
| <Furniture>
| -
| This tag marks the file as FURN.
|-
| <Header>
|
|
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag. Ignore it. Those flags were used in the past.
:None
:Locked
:PlacedInGame
:Temporary
:Gunk
|-
| <Position>
| float x3
| Optional tag. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag. X Y Z rotation.
|-
| <OSD>
| -
|
|-
|valign="top"| <Class>
|valign="top"| link
| File path to a '''pre-compiled [[XML:OFGA|OFGA]] (*.oni) file'''. Use it as part of a relative path. Make sure that the OFGA comes with the files it needs: M3GM and TXMP.

An OFGA can hold multiple M3GMs. That 3D content will then be integrated into the AKEV.
|-
|valign="top"| <Particle>
|valign="top"| string
| This name gets written into <Tag> inside ONLV (ENVP section) and can be used with BSL commands, e.g. you can take control over a particle via '''particle BSL_name start'''. For more commands, see [[XML:BINA/OBJC/PART#BSL_support|HERE]].

Take care with the naming of new OFGA files. The particle name will be composed of 2 parts separated by an "_" underscore. When one tag is empty, the final name will contain an underscore nonetheless. '''Examples:'''

: FURN <Particle>test</Particle> + OFGA <Tag>streetlight</Tag> = '''test_streetlight'''
: FURN <Particle></Particle> + OFGA <Tag>streetlight</Tag> = '''_streetlight'''
: FURN <Particle>test</Particle> + OFGA <Tag></Tag> = '''test_'''
|}

;Example

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Objects>
[...]
<Furniture>
<Header>
<Flags>Gunk</Flags>
<Position>-62.692 -29 108.35</Position>
<Rotation>181.522 356.021 178.114</Rotation>
</Header>
<OSD>
<Class>furniture/V_tctf_bigvan.oni</Class>
<Particle></Particle>
</OSD>
</Furniture>
[...]
</Objects>
</Oni>

====Physics.xml====
This file is for objects with "physics". Unlike AKEV core geometry or furniture, these objects can be animated.

: A small video tutorial on [https://www.youtube.com/watch?v=CFNseg_2UxA how to create a simple animated object]

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Physics>
| -
|
|-
| <Object Name="...">
| string
| Use a unique name for each object.
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Tested with BSL command...
:obj_create ID [ID]
:obj_kill ID [ID]
:env_anim ID [ID]
:env_setanim ID [ID]
The scripting ID will be stored in the ONLV's OBOA instance.
|-
|valign="top"| <Flags>
|valign="top"| flag
|
;Object setup flags
:None
:InUse
:NoCollision
:NoGravity
:FaceCollision
|-
|valign="top"| <Physics>
|valign="top"| flag
| Optional tag for an Object.
:None
:Static
:Linear
:Animated
:Newton (used with <Flags> FaceCollision to [https://www.youtube.com/watch?v=YICB7qugrtc make an object pushable])
:: For a pushable object don't use import sub-tags such as animation name, flags, etc. Just use <Import Path="..." '''/'''> or <Import Url="..." '''/'''>
|-
| <Position>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z rotation.
|-
| <Scale>
| float
| Optional tag of Object. Only used for non-animated objects.
|-
|
<Import Path="...">

<Import Url="...">
|valign="top"| link
|valign="top"| This tag comes in two variants. It doesn't matter what variant you use.
|-
| <Animation Name="...">
| link
| File path to *.dae file.
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag of Animation. For more information on those flags look [[XML:OBAN|OBAN]] page.

;Object animation flags
:None
:Loop
:PingPong
:RandomStart
:AutoStart
:Local
|-
| <End>
| integer
| Optional tag of Animation. Frame number. Used to define the end of an OBAN from a *.dae file.
|-
| <Start>
| integer
| Optional tag of Animation. Frame number. Used to define the start of an OBAN from a *.dae file.
|}

The XML code for physics can be written in two styles.
*The '''first style''' mimics the original structure found in extracted ONLV instances. This makes it '''easier to edit old levels and reimport them''' into the game.
*The '''second style''' was created with structured data (nested objects) in mind and is '''suited for totally new levels''' where animated objects must be created in a 3D editor at first.

'''Code style 1'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
<Object>
<Geometry>M3GMDishBase.oni</Geometry>
<Animation>OBANDishBase.oni</Animation>
<Physics>Animated</Physics>
<ScriptId>201</ScriptId>
<Position>-197.729141 128.46283 -2501.46387</Position>
<Rotation>0.7071067 -1.545431E-08 1.545431E-08 0.7071068</Rotation>
<Scale>2.109375</Scale>
<Name>object_DishBase</Name>
</Object>
</Physics>
</Oni>

'''Code style 2'''
:For documentation purposes, the file here has been trimmed down.

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
[...]
<Object Name="motorcycle">
<ScriptId>8</ScriptId>
<Flags>FaceCollision</Flags>
<Import Url="motorcycle/export.dae">
<Animation Name="motorcycle02">
<Flags>AutoStart</Flags>
<End>880</End>
</Animation>
<Animation Name="motorcycle02_stop">
<Start>881</Start>
</Animation>
</Import>
</Object>
[...]
</Physics>
</Oni>

In this example, OniSplit takes the file "export.dae", looks at the parts it contains, and creates geometry files from it.
* M3GMhubs_rear.oni
* M3GMhubs.oni
* M3GMmotorcycle.oni
It's convenient that hierarchies are supported here.

The motorcycle is made of 3 parts so 3 object animations ([[XML:OBAN|OBAN]]) will be created up to frame 880. Then OniSplit creates 3 more OBANs starting from frame 881.

The reason for the interruption at frame 880 is probably to give Barabas a little more camera time in the cutscene.

;Notes about BSL usage:

The Vago Lab cutscene script uses the motorcycle objects and animations like this:
env_show 8 0 # hide static motorcycle parts or else they would be visible
env_show 9 0 # while Konoko is still riding her animated motorcycle
env_show 10 0 # the static motorcycle is separated into objects 8, 9 and 10

# Static and animated objects are totally independent from each other.
# They are stored in different arrays so their script IDs can use the same numbers.

obj_create 8 10 # create all animation-ready motorcycle parts
env_anim 8 10 # animate those parts (not necessary if OBAN flag is "AutoStart")

# The first animations would loop because of "AutoStart", so get the
# right timing to apply the other animations. "motorcycle02_stop"
# and the others will not loop because they don't have "AutoStart".
env_setanim 8 hubs_stop
env_setanim 9 hubs_rear_stop
env_setanim 10 motorcycle02_stop

obj_kill 8 10 # delete all animated parts
env_show 9 1 # show static motorcycle model where Konoko parks her bike

====Corpses.xml====
An empty Corpse element (<Corpse />) is treated as unused and placed at the end of the array. If no such empty elements are provided, OniSplit automatically adds 5. OniSplit also ensures that there are at least 20 corpses in the array.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Corpses>
|
|
|-
|valign="top"| <Corpse>
|valign="top"| -
|
|-
| <Class>
| link
| [[XML:ONCC|ONCC]]''name''
|-
| <Transforms>
| -
| There are 19 <Matrix> for each <Transforms> (which represents a body part).
|-
| <Matrix>
| matrix
| Float 3x3 + float x3 for the last 3 values (X Y Z position). For more information about the matrix, see [[OBD:CRSA]].
|-
| <BoundingBox>
| -
| Bounding box of the whole corpse. Optional; if not provided, OniSplit will generate an approximate one. Currently it doesn't try to locate the ONCC to compute an exact bounding box.
|-
| <Min>
| float x3
|
|-
| <Max>
| float x3
|
|}

'''Trimmed example'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Corpses>
<Corpse>
<Class>generic_male_1</Class>
<Transforms>
<Matrix>-0.36488995 0.04620622 -0.9299034 -0.05580434 -0.9980576 -0.02769538 -0.9293768 0.04178688 0.366759717 -215.667755 1.603917 92.85312</Matrix>
<Matrix>0.2961557 -0.185628444 0.936928 -0.368288517 -0.9272724 -0.06730227 0.8812806 -0.32512787 -0.342981815 -216.51889 1.64218426 93.189</Matrix>
<Matrix>0.407847315 0.156575248 0.8995248 -0.238757968 -0.9326179 0.2705892 0.8812805 -0.3251278 -0.342982143 -215.239883 0.8405094 97.23532</Matrix>
<Matrix>0.439697325 0.467113584 0.767118752 0.0248355754 -0.8601105 0.5095029 0.8978026 -0.204975232 -0.389789373 -213.6234 1.46109009 100.80056</Matrix>
<Matrix>0.717241049 -0.179043233 0.673430443 0.4761817 -0.579636 -0.6612664 0.5087397 0.794962764 -0.3304816 -214.81662 1.56564879 92.5172348</Matrix>
<Matrix>0.3398023 0.1672905 0.925498843 0.7910236 -0.5831365 -0.185023025 0.5087395 0.7949628 -0.330481827 -211.71907 0.792413354 95.42558</Matrix>
<Matrix>0.1283634 0.227430075 0.965297 0.804142356 -0.59352535 0.032904774 0.5804117 0.7720126 -0.259073079 -210.372269 1.45546341 99.0937653</Matrix>
<Matrix>-0.285799921 0.06851995 -0.955836535 -0.240357026 -0.970681965 0.00228381017 -0.927656651 0.230394751 0.2938901 -216.284851 1.5839076 91.29168</Matrix>
<Matrix>-0.312039882 0.04875436 -0.948817253 -0.176752359 -0.9842264 0.00755515043 -0.9334825 0.1700632 0.31573534 -216.689789 1.68287766 89.9359055</Matrix>
<Matrix>-0.356412441 -0.5390179 -0.763170958 0.0404523835 -0.82494843 0.5637587 -0.933452547 0.170058519 0.315826446 -217.422012 1.7979821 87.70907</Matrix>
<Matrix>-0.101782769 -0.247171819 -0.9636112 0.5426916 -0.8256094 0.154451028 -0.8337422 -0.507223248 0.2181709 -217.747284 1.30605173 87.0125656</Matrix>
<Matrix>-0.8154478 -0.150626346 0.558888733 -0.1200991 0.9885643 0.09119747 -0.566234052 0.00724477554 -0.8242127 -217.7402 2.065678 88.15346</Matrix>
<Matrix>-0.4593738 -0.326781839 0.825947642 0.8874048 -0.1284554 0.442732215 -0.0385793857 0.9363295 0.348996729 -219.093979 1.81561315 89.08131</Matrix>
<Matrix>-0.9545983 -0.13777709 0.26412034 0.295387268 -0.322961926 0.899134 -0.0385792255 0.9363296 0.348996431 -220.3681 0.9092429 91.37218</Matrix>
<Matrix>-0.9715769 -0.0362956524 0.233924776 0.0276728421 -0.9988148 -0.0400396362 0.2351007 -0.0324283168 0.9714299 -222.775482 0.56178683 92.03825</Matrix>
<Matrix>0.979860842 -0.192433611 0.0533096045 0.193336874 0.9810555 -0.0122905634 -0.0499345176 0.0223497637 0.9985025 -216.8387 1.90143847 87.84845</Matrix>
<Matrix>0.863898 -0.399280578 0.3070101 0.171117 -0.340619326 -0.9244986 0.4737078 0.851207137 -0.225936681 -215.211975 1.58196676 87.93695</Matrix>
<Matrix>0.4673251 -0.0255063027 0.883717656 0.746463835 -0.524209559 -0.4098731 0.4737075 0.851207256 -0.225936785 -212.815842 0.47451216 88.78848</Matrix>
<Matrix>0.216871262 -0.007893051 0.976168454 0.3751846 0.9238389 -0.0758833 -0.9012231 0.3827002 0.203315422 -211.637314 0.410188764 91.0171051</Matrix>
</Transforms>
<BoundingBox>
<Min>-219.731216 -2.258905 84.47974</Min>
<Max>-207.518463 4.49535131 104.023239</Max>
</BoundingBox>
</Corpse>
</Corpses>
</Oni>





[[Category:Modding tutorials]]

Modding errors

2025-01-22T06:36:04Z

Vortice: /* Frequently asked questions */Fixed broken link.

You might want to use the browser's search function to quickly find an error message.
{{TOClimit|3}}
==Frequently asked questions==
[[Image:modding_errors.jpg|thumb|200px]]

*Why does Oni crash on game start?
::What were you working on? A [[#... due to overloaded animation|character animation]]?
*Why does Oni crash while loading a level?
::What were you working on? A [[#... due to missing files|game level]]?
*Why does a character have black body parts?
::You're probably [[#Missing character texture (TXMP)|missing a texture]].
*Why does a character have white body parts?
::You are using a mod with bgra32 textures and an old engine that doesn't support bgra32.
* Why can't I convert character animations?
::See [[#TRAM-related|HERE]] if you use "-create:tram".
* Why are all body parts overlapping in the DAE file?
::Because the part hierarchy isn't correct. Read more [https://web.archive.org/web/20160225191109/http://oni.bungie.org/forum/viewtopic.php?pid=31310#p31310 here].

==Visual errors based on settings==
===Black splashscreens but normal gameplay===
Those screens (all TXMBs) are black if the user has a lower resolution than the screen. Oni's vanilla splashscreens are 640x480 but the [[AE]]'s "HD Screens" package bumps them up to 1024x768, which is where players usually encounter this problem.

'''Note''': This problem is fixed by [[Daodan DLL]] v3.5 or newer and the [[FERAL|Mac Intel build]] v1.2 or newer.

==Binary errors==
===Crash while starting Oni===
====... due to overloaded animation====
Animations with more than 107 keys per bone crash the game. You can import animations with more than 107 frames if the keys cover multiple frames.
: For example 12 frames ''<EKey>'''12''' -156.628983 -14.6175327 -78.3831558</EKey>''
Such ranges and EKeys are produced by older OniSplit versions. See [[#TRAM-related|HERE]].

'''Note:''' You shouldn't encounter this bug anymore with OniSplit v0.9.56.0 or newer.

===Crash while loading a level===
====... due to improper textures====
Textures' x and y (pixel) dimensions must be a power of two: 512, 256, 128, 64, etc.

====... due to missing files====
Generally it can be said that Oni complains when an instance is missing that is referenced by another instance. For instance:
* AKEVs don't tolerate missing textures.
* ONVLs and ONCCs don't tolerate missing variants (ONCVs).

====... due to triangle limit====
* with too many triangles, Oni crashes after ~90% of the loading process; the triangle limit is ~520,000 (500,000 to be on the safe side).

===Crash while playing===
====... due to missing files====
If you encounter a crash when spawning a character or when you cycle through all characters with F8, then check if the crashing character has a TRMA file.

===Non-crash errors===
These errors are visible inside the game and don't cause a crash when they appear.

====Multiple savegame names for same level number====
The Load Game menu can show additional savegame names if any new ONLV is provided in another level0 plugin. As a quick test, you should use a plugin name which comes alphabetically before "level0_Final", such as "level0_Addin". If you choose a name like "level0_More", the new savegame will be appended after all "_Final" ONLDs, and also a clone appears:

: "_Final" list
: new savegame name from "_More"
: cloned savegame name of the slot meant to be overwritten

====Multiple TXMBs====
A level can start with multiple TXMBs, visible one by one, although there was just one BSL command calling for one. This is caused by using additional plugins, because files with the same name can stack.

====Missing character texture (TXMP)====
The texture is either missing, or the texture name and the link in [[OBD:TRMA|TRMA]] do not match.

====Distorted colors in textures (TXMP)====
[[Image:color_spectrum_test.jpg|thumb|200px]]

Why do my source and re-extracted textures look okay but in-game the colors are distorted? The "[[OBD_talk:TXMP#0x_00_10_00_00|little endian data]]" flag in the level data file is missing. The flag will be added by OniSplit v0.9.56.0 or later when you import it, or you can create the TXMP via an XML file and ensure that the flag is present before import.

====Missing animation collection (TRAC)====

====Missing 3D model (TRBS)====

====Distorted 3D model (TRBS)====
[[Image:XSI_Konoko_Ref.png|thumb|200px]]

When creating the 3D model in Mod Tool, you have to watch out for the naming and order of the body parts.
* If you use OniSplit v0.9.58.0 or lower, the naming of body parts must be absolutely correct.
* If you use higher versions, the naming is unimportant but the order matters. The order can be easily changed in the Schematic [9]. Then go to Edit > [http://edt.oni2.net/images/schematic.jpg Reorder Nodes Tool] [I] and move an object to its new position.

====Non-working combos (TRAM)====
Situation: When you create combos, you want to test your moves in-game. Sometimes each move actually works (tested via chr_animate) but the combo does not.

Requirements to prevent that bug:
* <Attacks> and <HorizontalExtents> data is needed
** '''Note:''' With OniSplit v0.9.55.0 or newer, HorizontalExtents (now named "[[XML:TRAM#List_of_tags.2C_types.2C_and_flags|AttackRing]]") is calculated automatically.
* Correct links to the Direct Animations tag
* Correct links inside the character's animation collection (TRAC)

==Developer Mode error messages==
===Animation errors===
''throwtarget was NULL'' - The throw target animation was not found.

===BSL errors===
*''Func "main", File "(called from engine)", Line 0: semantic error, '''function''' "main" '''does not exist''''', then either the function "main" wasn't found in any BSL file (this can also happen with any other function), or the BSL file has too many commands in it (see [[#BSL_commands_per_file_limitation|here]]). If it's the latter, split your BSL file into more BSL files (creating additional functions if necessary).

* ''Func "(null)", File "test.bsl", Line 3: semantic error, '''Identifier''' "main" already declared'' - In this example, there are multiple "main" functions; the last occurrence of main() can be found in the file "test.bsl" at line 3.

* ''Func "(null)", File "main.bsl", Line 1: Illegal token, got "func" expected ";"'' - A previous variable declaration didn't end with a semicolon.

* ''SLiSchedule_Task_Find FAILED [IMPORTANT]'' - The game will freeze after about 5 instances of this message. Caused by calling too many BSL functions in parallel (using fork) in a very short amount of time.

====Mistyped variable====
Typing ''chr_lod 4'' will produce this error: ''Func "(null)", File "(called from console)", Line 1: Illegal token, got "0" expected ";"''. That's because "chr_lod" is a variable and you need to use the equals symbol to set a variable. The correct use of this variable would be ''chr_lod = 4''.

====Mistyped function====
Typing ''killled_griffen = 1'' will produce ''Func "(null)", File "(called from console)", Line 1: semantic error, symbol "killed_griffen" is not a variable (function most likely)''. That's because "killed_griffen" is a function, and you simply list values (parameters) after function names, with no equals symbol. The correct use of this function is: ''killed_griffen 1''.

Another incorrect example: Typing ''chr_givepowerup = 0 ammo 1'' will produce:
: ''Func "(null)", File "(called from console)", Line 1: semantic error, symbole "chr_givepowerup" is not a variable (function most likely)''
: ''Func "(null)", File "(called from console)", Line 1: Illegal token, got "ammo" expected ";"''
The correct use of this function is ''chr_givepowerup 0 ammo 1''.

====BSL commands per file limitation====
The engine has some kind of limit on how many BSL commands can occur in a single BSL file. When you pass the limit, you'll get errors in the developer console like this: "Func "main", File "(called from engine)", Line 0: semantic error, function "main" does not exist." (it can also be a function other than "main").

For an example, extract these files and place them in IGMD/EnvWarehouse to experience the problem: [http://script10k.oni2.net/wikifiles/main_not_working_without_commenting_commands.zip], [http://script10k.oni2.net/wikifiles/main_not_working_without_commenting_commands(functions_splitted).zip], [http://script10k.oni2.net/wikifiles/main_splitted_in_two_files.zip]

In all these BSL files, the message "This message should appear on the beginning" should appear when you load level 1. However for "main_not_working_without_commenting_commands" it doesn't work unless you comment out the 5th line of the BSL file. The "main_not_working_without_commenting_commands(functions_split)" script is the same, but in this one the "main" function is split into two functions, which is still not enough for the error to go away. The scripts in "main_split_in_two_files" are the same BSL as previously, but the two functions are split into two different files: "main.bsl" and "continuation.bsl". In this case the script works as expected, and the message "This message should appear on the beginning" appears on level load.

So if you experience the error "Function "x" does not exist." when in fact it does, try spreading your functions across more BSL files and it should fix the problem.

==OniSplit error messages==
===TRAM-related===
* ''COLLADA error: duplicate id light'' - Maybe your DAE file has more than one root scene. In this case, you can right-click the model (which selects all 19 bones), then go to the Crosswalk settings, check "Selection Only", and save the file.
* ''.dae files cannot be imported as TRAM'' - Newer OniSplit versions doesn't seem to support "-create:tram" any longer. If you use that command, download an older version like v0.9.41.0 from Mod Depot.
* If TRAM*tgt has more than 256 (0-255) frames, you'll see:

Parametername: Value too large for Byte
at Oni.BinaryWriter.WriteByte(Int32 value)
at Oni.Totoro.AnimationDatWriter.WriteRotations(List`1 rotations, Int32 frameSize)
at Oni.Totoro.AnimationDatWriter.WriteAnimation()
at Oni.Xml.XmlImporter.ReadAnimation()
at Oni.Xml.XmlImporter.Import(String filePath, String outputDirPath)
at Oni.Program.ExecuteTasks(String[] args, String outputDirPath, Set`1 importedFiles, Queue`1 taskQueue)
at Oni.Program.CreateGeneric(String[] args)
at Oni.Program.Execute(String[] args)
at Oni.Program.Main(String[] args)

===TRBS===
In DAE files, if a bone has a point cluster, OniSplit v0.9.94.0 fails to convert the file.

==AE Installer==
===Blank mod list===
Your user account probably doesn't have the necessary rights that the AE Installer needs. In Windows, this can happen if you have Oni installed on an ''old'' hard drive which is now wired to your new system. Add "full control" to your account by right-clicking the Oni folder, choosing Properties, and going to the Security tab.

==XSI/Mod Tool errors==
===Corrupted DAE files===
Situation: ''I cannot load my DAE file into XSI. It give me an "Unspecified Failure".''

Possible cause: When you create the DAE file, there are file paths are stored inside it. If a path contains an illegal character, XSI cannot load the file.

Solution: Make sure the paths use only letters of the [[wikipedia:English_alphabet|English alphabet]].

===Object with test texture===
If the texture's file name contains a "#", ModTool fails to apply that texture and use its rainbow-colored test image instead.

[[Category:Modding tutorials]]

Modifying textures

2025-01-22T06:32:12Z

Vortice: Fixed a broken link.

Here are some brief instructions on how to modify the texture maps. You might want make new skins for a character or even a new outfit for Konoko!

'''Extract TXMP''' (Texture maps)
:1) Make a folder for the textures to go into ("tex_folder" below).
:2) You will need to 'cd' (change directory in the terminal) to AE/AEInstaller/vanilla/.
:3) To extract all the TXMPs, use the following command:
:onisplit -extract:png tex_folder level0_Final.dat

:For example:
:PC users: onisplit -extract:png tex_folder level0_Final.dat (Or you can use -extract:tga to get the files in Targa format)
:Mac users: mono onisplit.exe -extract:png tex_folder level0_Final.dat
:3) Now all the TXMPs from Oni (over 2,000) will be located in the Oni/TXMPfiles

'''Modify TXMP'''
:1) Currently, many of Oni's texture maps are 64x64, or 128x128; unmodded, Oni supports textures up to 256x256, but the current patched version of Oni for Windows supports 512x512, and the patched version of Oni for macOS supports up to 1024x1024.
:2) Use your favorite graphic editor to make your changes.

'''Create TXMP*.oni files'''
For most image files you can use the following command:
:PC: onisplit -create:txmp destination_directory options source_image_file
:Mac: mono onisplit.exe -create:txmp destination_directory options source_image_file

: The source_image_file can be dds or tga. "Color indexed" and "black and white" tga files are not supported currently. Other image file formats (png, jpg, bmp, tif) may work depending on Mono/.NET support for them. onisplit will automatically prepend TXMP to the output file name if the source file name does not start with TXMP already.

:Options can be
:-nouwrap - set the "U wrapping disabled" flag
:-nowwrap - set the "V wrapping disabled" flag
:-format:bgr555 (or dxt1) for most of the stuff
:-format:bgr32 for skyboxes
:-format:bgra4444 for transparent/reflective stuff (in a couple of places bgra5551 is used but probably it's not big deal if bgra4444 is used instead)
:-genmipmaps - generate mipmaps if they are not already present in the source file and if the source file is not dxt1 compressed
:-envmap - envmap used for reflectivity

:Here is an example
:PC: onsplit -create:txmp dest_dir -format:bgr555 -genmipmaps TXMPSTR_EASY_1%2FSTRbicepR.tga
:Mac: mono onisplit.exe -create:txmp dest_dir -format:bgr555 -genmipmaps TXMPSTR_EASY_1%2FSTRbicepR.tga

:To batch process a folder you can use this command;
:PC: onisplit -create:txmp dest_dir -format:bgr555 -genmipmaps folder_of_images\*.tga
:Mac: mono onisplit.exe -create:txmp dest_dir -format:bgr555 -genmipmaps folder_of_images/*.tga

:For image files that use an envmap (Such as Striker armor, Ninja armor, Elite armor, Konoko's face, weapons), you will need to include the name of the envmap:
:PC: onisplit -create:txmp dest_dir -format:bgra4444 -genmipmaps -envmap:envmapname imagefile.tga
:Mac: mono onisplit.exe -create:txmp dest_dir -format:bgra4444 -genmipmaps -envmap:envmapname imagefile.tga

:3) Once you have created the TXMP*.oni file, you will need to put it in the level0_Final folder and then recompile the level.

:4) Play the game and see how your new texture maps look.

'''TXMP & XML'''
:Extracting a texture with -extract:xml produces an xml file and one or more tga files. The xml file will contains texture options like format and flags and a list of tga file names.
:* options for <Flags> (more than one are separated by a double space) : None HasMipMaps DisableUWrap DisableVWrap AnimUseLocalTime AnimBackToBack AnimRandom AnimIgnoreGlobalTime ShieldEffect InvisibilityEffect DaodanEffect
:* options for <Format> : ARGB4444 / RGB555 / ARGB5551 / RGB888 / DXT1
: More than one tga file is produced for animated textures and the filenames look like TXMPsmoke_001.tga, TXMPsmoke_002.tga etc.
:Using the -create option with such an xml file will produce a normal TXMP.oni file but without the need to specify additional parameters on the command line like with -create:txmp. This comes in handy if you want to edit a bunch of textures:

:* put all the xml and tga files in a single directory
:* edit tga image files as you need
:* in the directory you can run the command: onisplit -create oni *.xml to create all TXMP.oni files in the subdirectory oni.

:Tip:
:The exported xml file does not contain the width and height of the texture, this is obtained from the tga file. If you resize the tga file the texture will be resized too.

'''Reflective textures'''

:Keep in mind, Oni simulates reflectivity using textures and alpha channels.

:To see how a reflective texture is made, extract TXMPSTR_HARD_1%2FSTRchest.oni as XML. You will get a TGA and XML file.
:Open the TGA file in a photo editor and it has an alpha channel. The alpha channel determines what part of the texture is reflective. Black in the alpha channel means no reflectivity, gray to white is increasing amounts of reflectivity.

:Now in the XML file, there are 2 properties you will be concerned with:
:<Format>ARGB4444</Format>
:<EnvMap>TXMPstrikerarmor</EnvMap>

:The <Format> is how the texture will be saved. In this case, the striker's chest texture was originally saved with an alpha channel. Now there are 3 formats that can have an alpha channel:

:ARGB4444 = 4,096 colors, alpha 16 colors
:ARGB5551 = 32,768 colors, alpha 2 colors
:ARGB8888 = 16,777,216 colors, alpha 256 colors (Note: this one requires the Oni engine to be patched and not many have the patched version)

:The <EnvMap> refers to what texture is used to simulate reflectivity. There are 4 envmap files that are used for characters:
:TXMPstrikerarmor
:TXMPenvksface
:TXMPenvksarmor
:TXMPSUPER_REFLECT

:You might want to extract this file as xml to see its properties.

:Once you make your texture that has an alpha channel, use the XML file to convert it back to .oni file.
(from here: https://web.archive.org/web/20160226055825/http://oni.bungie.org/forum/viewtopic.php?pid=19297#p19297, to be edited and completed)

[[Category:Modding tutorials]]

OniSplit

2025-01-22T06:28:03Z

Vortice: /* Levels */Fixed broken forum link.

{{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] ([https://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/Naming|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 [https://web.archive.org/web/20201127180431/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]]

SketchUp tutorials and tips

2025-01-22T06:26:03Z

Vortice: /* Tutorials */Fixed broken forum links.

==Tutorials==
{| border=1 cellpadding=5
! Tutorial
! Author
! Link
! Status
! Notes
|-
| How to make a simple level
| [[User:Lukas Kreator|Lukas Kreator]]
| [https://web.archive.org/web/20190712222844/http://oni.bungie.org/forum/viewtopic.php?pid=35324 Oni Central Forum]
| Finished, but outdated
| Replaced by the tutorial below
|-
| Creating the Lair - A level tutorial
| [[User:EdT|EdT]]
| [https://web.archive.org/web/20201029114347/http://oni.bungie.org/forum/viewtopic.php?id=2087 Oni Central Forum]
| Finished
|
|}

==Tips==
([[User:EdT|EdT]]: You are welcome to put some tips here, about the doors and lasers for example...)

===Faces===
Faces are made when you draw a rectangle, a triangle or a polygon. For example, a cube has 6 faces, because it is made of 6 squares. You could also consider the faces inside the cube, if it is hollow. Faces with no textures show in SketchUp as white or blue. White means it is a "front face", blue means it is a "back face". Oni will not draw back faces, and you cannot collide with them. You can flip the faces using Right Click -> Invert Faces, after selecting one or more faces. I suggest that you first invert back faces, and then texture the level. In old versions of OniSplit, back faces have to be textured too, in order for the level to be converted to AKEV successfully.

===Stairs===
[[Image:Stairs with invisible ramp.png|thumb]]
If you want to make stairs, make the steps very small or make a ramp over it with an invisible texture. You can use [http://iritscen.oni2.net/wiki/Lukas%20Kreator-Invisible512px.png this all-transparent texture]. The stairs should then look like the image on the right.

===Rotating geometry===
Some things may be rotated when you try to load your level in Oni. This seems to happen when the user groups stuff together and forgets to ungroup them later. There are two ways to fix it:
* Load your level in XSI Tools and export the .dae from there. Does not work always.
* Try to find what is grouped and ungroup it.

===Yellow faces===
A weird phenomenon happened when an user from OCF (Delano762) was making a new level. There were yellow faces on some places. It is currently unknown what these are, but they seem to have been generated when he converted a Counter Strike map to a COLLADA .dae through a tool. According to him, he was unable to change the texture of these faces if he selected all faces in the level at the same time, but he could change them back to the default texture one at a time.

===Common errors===
* If your level was converted successfully by OniSplit, but when you try to play it, Oni crashes after about 10% of loading the level, this means there are textures in the model that were not included in the level folder. For example, the model uses TXMPtexture, but TXMPtexture.oni is missing from the level files.
* If you cannot convert your level to AKEV because OniSplit throws an error, you could be missing textures on some faces. Back faces also have to be textured, as far as I know.
** Note: This does not occur with the latest OniSplit, if a face does not have a texture, OniSplit will assign TXMPnotfoundtex to that face. So there is no need to assign textures to back faces. - [[User:EdT|EdT]]
* Sometimes OniSplit may throw an error similar to this: "Unsupported primitive type "<something>" found in geometry "mesh<number>-geometry", ignoring". I usually ignore this, because I don't know any case in wich this was a problem. Please, correct me if I'm wrong.

[[Category:Modding tutorials]]

Using the Rigify animation rig

2025-01-22T06:15:08Z

Vortice: /* Tools and relevant tutorials */Fixed broken forum link to archive

==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.
* [https://web.archive.org/web/20211202215118/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.app/ '''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]]

Creating a level

2025-01-22T04:12:39Z

Vortice: /* Vertex coloring */Broken forum link to archive

This page covers level creation from scratch. See [[Modifying an existing level]] if you want to change a vanilla level in the game.

==Level releases and resources==
===Fan-made levels===
{| class="wikitable sortable autosort by-column-3"
!Date
!Name
!Level number
|-
|TBA
|Oni 2 Angel Studios Tour
|32
|-
|TBA
|Green Room
|26
|-
|2019/09/16
|[https://web.archive.org/web/20240527004257/http://oniforum.bungie.org/viewtopic.php?id=2965 Omega Tournament]
|31
|-
|2016/02/13
|[https://web.archive.org/web/20160224173743/http://oni.bungie.org/forum/viewtopic.php?id=2947 AI Battle]
|7
|-
|2014/01/19
|[https://web.archive.org/web/20211202225410/http://oni.bungie.org/forum/viewtopic.php?id=2698 Wilderness Preserve]
|17
|-
|2013/09/07
|[https://web.archive.org/web/20201127180732/http://oni.bungie.org/forum/viewtopic.php?id=2656 Island]
|29
|-
|2013/07/12
|[https://web.archive.org/web/20201127175459/http://oni.bungie.org/forum/viewtopic.php?id=2640 City]
|28
|-
|2013/06/01
|[https://web.archive.org/web/20201029102326/http://oni.bungie.org/forum/viewtopic.php?id=2619 Fight Club]
|25
|-
|2012/05/12
|[https://web.archive.org/web/20220701102842/http://oni.bungie.org/forum/viewtopic.php?id=2357 Old China]
|24
|-
|2012/03/18
|[https://web.archive.org/web/20211202220454/http://oni.bungie.org/forum/viewtopic.php?id=2302 Boss Battle]
|23
|-
|2012/02/12
|[https://web.archive.org/web/20201029113554/http://oni.bungie.org/forum/viewtopic.php?id=2271 De Dust Deluxe]
|22
|-
|2012/01/23
|[https://web.archive.org/web/20201029114415/http://oni.bungie.org/forum/viewtopic.php?id=2242 Parkour Challenge 2]
|21
|-
|2012/01/16
|[https://web.archive.org/web/20211205145843/http://oni.bungie.org/forum/viewtopic.php?id=2235 Parkour Challenge]
|21
|-
|2011/07/25
|[https://web.archive.org/web/20201029103607/http://oni.bungie.org/forum/viewtopic.php?id=2001 Mini-Partenon]
|5
|-
|2011/10/03
|[https://web.archive.org/web/20201029113340/http://oni.bungie.org/forum/viewtopic.php?id=2024 Muro's Lair - Preview]
|20
|-
|2011/07/03
|[https://web.archive.org/web/20201029113724/http://oni.bungie.org/forum/viewtopic.php?id=1957 Hexagon]
|16
|-
|2011/06/23
|[https://web.archive.org/web/20201029104928/http://oni.bungie.org/forum/viewtopic.php?id=1938 Junkyard]
|15
|-
|2011/05/01
|[http://mods.oni2.net/node/178 Arena of Hurt (OZG)]
|7
|-
|2010/11/08
|[https://web.archive.org/web/20210117150652/http://oni.bungie.org/forum/viewtopic.php?id=1736 Arena of Hurt (OTA)]
|7
|-
|2010/11/06
|[https://web.archive.org/web/20201029105217/http://oni.bungie.org/forum/viewtopic.php?pid=50565#p50565 Martian Colony] AKA "Silly World"
|5
|-
|2010/02/15
|[https://web.archive.org/web/20201029113916/http://oni.bungie.org/forum/viewtopic.php?id=1506 Maze]
|5
|-
|2008/09/16
|[http://mods.oni2.net/node/4 Arena of Pain]
|30
|-
|2024/05/20
|[https://gamebanana.com/mods/514707 Kitsune: Chapter 1]
|20
|}

===Forum tutorials on level creation===
* '''[https://web.archive.org/web/20201029114347/http://oni.bungie.org/forum/viewtopic.php?id=2087 "Creating the Lair - A level tutorial"]'''
* [https://web.archive.org/web/20201127172559/http://oni.bungie.org/forum/viewtopic.php?pid=53026 "Creating a Custom Oni Level (s10k video tutorials)"]
* [https://web.archive.org/web/20201127180431/http://oni.bungie.org/forum/viewtopic.php?id=1515 "Creating new levels"]
* [https://web.archive.org/web/20201029114358/http://oni.bungie.org/forum/viewtopic.php?pid=33838 "Create levels with pathfinding grids"]
* [https://web.archive.org/web/20210117145338/http://oni.bungie.org/forum/viewtopic.php?id=2000 "More questions about levels"]
* [https://web.archive.org/web/20201029103906/http://oni.bungie.org/forum/viewtopic.php?pid=37252#p37252 "Modding Existing levels - Beta" ("Moveable furniture" post)]

===Wiki pages on level creation===
* [[Creating a level]] (you are here)
* [[Modifying an existing level]]
* [[New levels]]
* [[Lightmapping levels]]

===Free asset sources===
* [http://vk.com/gameready Various game meshes]
* [http://web.archive.org/web/20230601050258/http://tutorialsforblender3d.com/Textures/Textures_index.html Various game textures]
* [https://www.textures.com Various game textures]

==Engine limitations==
First you should be aware of the limitations that Oni will place on your level.

* The triangle limit of a game level is approx. 520,000 (consider it 500,000 to be on the safe side).
* {{ModTool}} can save DAE files with a maximum of 64,000 triangles per object.
* When polygons are too tightly packed, the camera will look at too many of them and glitches will appear. The limit on visible GQs (Gunk Quads) is 8,192 (213), and higher numbers will cause render bugs and produce the console error message "Exceeded max visible GQs ''number''". There are limited solutions to this:
** Decrease the '''gs_farclipplane_set''' value.
** Hide objects via '''[[#.3CModel.3E|env_show]]'''.
** Hide objects by ''level design''. For example, departments in a building could be quite detailed because the view of the other departments/rooms is blocked by walls.
* The camera can look at 2,049 transparent textures at once; one more, and Oni crashes.
* Characters are visible ''only'' within world coordinates {-4,099, -4,099, -4,099} to {4,099, 4,099, 4,099}.
* Geometry stops outside of (roughly) world coordinates -4,228 to 4,228 on the X and Z axes (vertical axis not tested).
* '''chr_debug_spheres = 1''' visualizes the collision spheres of characters, so you can check if they will fit through an entrance.

==3D tools==
===Problems when using multiple different tools===
Re-saving a DAE file in '''Mod Tool''' which was originally made in '''SketchUp''' can result in a surprising change in size within Oni. This is due to a difference in the specification of a scale unit.

: For example, the SketchUp DAE file may have: <tt><unit meter="0.0254000" name="inch" /></tt>
: And the re-saved Mod Tool DAE file may have: <tt><unit meter="0.1" name="decimetre"></unit></tt>

In that case you'll need to open the new DAE in a text editor and change the length specification back.

===Sketchup===
If you are working with Sketchup check out this pages:
* [http://oni.bungie.org/forum/viewtopic.php?id=2003 "Sketchup tutorials for making levels"]
* [[SketchUp tutorials and tips]]

===Blender===
'''Scaling'''

Same as Mod Tool and SketchUp: Caution with scaling: See [[#Problems when using multiple different tools|here]]

'''Pathfinding'''

Be sure to uncheck automatic triangle creation when exporting (BNV) geometry used for pathfinding. Ghost (''doors'') must be quads.

==Setting up a workflow==
If not noted differentely you need OniSplit v0.9.82.0 or a newer version. Onisplit can be downloaded [http://mods.oni2.net/node/38 HERE] (it also comes with the [[AE]] and is found in the Tools directory of the installation).

The level import demo files can be downloaded [http://mods.oni2.net/node/299 HERE].

First, put '''OniSplit.exe''' into the second '''lab''' folder alongside the XML files.

Look at the file '''build.cmd'''. These are the two important lines:

OniSplit.exe -create:level out lab.xml
OniSplit.exe -import:pc out level3_Final.dat

The first line creates the *.oni files from a master.xml file, in this case '''lab.xml'''. Once finalized, the resulting .oni files can be put into a new [[Making a mod package|AE package]].

The second line creates level archives which can be used for fast tests. They don't require you to install a package through the AE Installer.

Instead of "-nosep" you can now also use "-pc" for the import. Macs, however, do use "-sep".

==Troubleshooting==
If the game crashes while loading at ~90% progress, be sure that the texture's x and y dimensions are powers of two: 64, 128, 256, 512….

If the game crashes while loading at ~50-60% progress, be sure that the BINACJBOCharacters or AISA file has a player character defined.

If the game crashes while loading ~5-10% progress, check if all your textures were inside the "out" folder.

:You can extract the AKEV file to XML, then search for the [[XML:AKEV#TXMA|TXMP Array]].

:[http://mods.oni2.net/system/files/AKEV_texture_checker.txt THIS] script checks which textures are missing by comparing the AKEV*.xml with its *.oni files folder. Change the two paths so that it works for you: Alt+4, insert code, then F5.

"TXMP_marker_door" and "TXMP_marker_ghost" will be missing in the demo's "out" folder.

You can add this between the other two lines in build.cmd to prevent a crash.
OniSplit.exe -create:txmp out env/markers/*.tga

==Terminology==
;Polygon
:A polygon is a shape defined by points (vertices) in space. Polygons are the most fundamental building block in games. Oni uses only shapes with 3 and 4 points (triangles and quads). Other games might also use N-gons, shapes with more points.
;Face
:The '''surface of a polygon''' is also named face. The '''direction''' of a face in '''defined by its normal'''. If an object seems to have a hole, it might be that the polygon just has a '''flipped normal''' and is therefore wrongly rendered (displayed on screen).
;Normal
:Faces and even vertices themselves have directions. The normals of vertices determine how smooth or sharp edges will appear.
;Vertex (plural<nowiki>:</nowiki> vertices)
:A point within a polygon.
:Vertex colors radiate from one vertex to another vertex, whereby their different color values blend into each other so that gradients can appear.
;Edge
:A line of two points within a polygon.
;Tris (triangles)
:Polygons made of 3 points.
;Quads
:Polygons made of 4 points. Planes. Rectangles.
:Internally, all quads get converted into two triangles and will affect the maximum triangle count accordingly.
;Level
:The term "level" is often used to shorten "level map" (buildings and terrain).
;Geometry
:Level geometry can be objects made of tris and/or quads.
:Oni differentiates between basically 3 types of level geometry:
:* Static objects (sometimes also named AKEV core geometry)
:* Animated objects
:* Pushable objects (not used in the original game)
;Static geometry
:* '''Unique level geometry with no functions''' (AKEV core geometry such as buildings and streets).
:* '''Repeating objects''' are flagged as '''furniture (FURN)''' although they can be outdoor objects such as boxes and containers. FURN objects were used to be imported by an object collection, an CJBO. Nowadays, furniture collections can be used (again) for imports, but the individual objects are stored as OFGA files. This modularity is known in many game editors (like the Unreal Engine Editor). So, '''OFGA are nothing else than "game assets".''' The drawback of OFGA is that they '''will not import with any vertex shading'''. Only their '''geometries''', attached '''particle''' and '''gunk flags''' get copied into final (baked) level geometry.
:* '''Objects with actual functions''' (CJBO such as doors, consoles, triggers)
:** Some types of CJBO (spawn lists of weapons, characters, powerups and of course flags and patrol paths) are not considered as level geometry.
;[[XML:AKEV#AGQG|Gunk flags]]
:Properties directly associated with the polygons. Among others, these can be: Transparent, TwoSided, NoCollision, Invisible, NoObjectCollision, NoCharacterCollision, NoDecals, Furniture, Impassable.
;Baking
:When a level gets baked, all geometries get merged.
:*Unique level geometry will have vertex painting.
:*Objects derived from already compiled oni-files (shared classes) will have no vertex painting.
:*Animated and pushable objects will have no vertex shading.
;Vertex shading
:Vertex colors (vector data) can be painted onto core geometry.
:They are used as a rudimentary form of lightmapping (pixel data).
:Having vertex shading is still better than having no vertex shading at all. It makes the level appear more lifelike.
;Lightmapping
:In other games, lights and shadows are added to level geometry with lightmapping.
:There were experiments to bring lightmaps back to Oni. The technique come with a major drawback though. It doubles the triangle count and adds many textures.
;In-game
:When you are "inside" the game, running or playing it.

==Level construction==
'''Visible environment'''
* A '''level map''' consists of visible geometry: terrain and buildings. This is also named the '''environment''' or for short '''env'''.
** Use '''quads''' of approximately 10 up to 20 meters in size to construct env geometry.
* Anything other than floors and simple walls will be made of triangles.
** Geometry from CJBO works best with triangles. Quads might show holes in-game.
'''Invisible pathfinding'''
* '''AIs''' (or non-player characters, NPCs) need '''pathfinding''' data, usually shortened as '''bnv'''.
** Pathfinding data can be described as geometry, therefore as rooms. These '''bnv rooms''' are made of '''floors''' and are connected by '''ghost''' quads which work like doors. AIs can move from one room to another room only by passing a ghost. Therefore, ghosts have the same width as rooms in open terrain.
*** Use floor quads of approximately 10 meters in size to construct BNV floors.
*** Put ghost quads exactly on the edges of BNV floors with an angle of 90 degree.
'''Support for [[XML:BINA/ONIE|effects]]'''
* Effects such as decals that indicate damaged environment need level textures to be registered in [[XML:BINA/TMBD|TMBD]]. Make sure not to replace existing texture entries but to add your own so that the other levels remain unaffected.
'''Level logic'''

BSL scripts bring levels fully to life. The logic is mostly event driven whereby different checkpoints and conditions must be reached.
* Checkpoints are actually [[XML:BINA/OBJC/TRGV|trigger volumes]] that can recognize entering and exiting characters.
* The second most important source of events are [[XML:BINA/OBJC/CHAR|character (script) functions]], especially the die function of enemies.
** To support good and less good players alike, NPC characters can feature the UpgradeDifficulty flag. Also, BSL scripts can detect the current [[BSL:Game_status|difficulty level]].
* [[XML:BINA/OBJC/TRIG|Laser triggers]] are mostly used to control [[XML:BINA/OBJC/TURR|turrets]]. [[XML:BINA/OBJC/CONS|Consoles]], triggers and [[XML:DOOR|door]] unlocking are used to set up very simple "riddles”.
* The creation of cut scenes is time-consuming quality work. Due to missing tools for streamlined workflows, it is totally okay for you to skip this.
** New synchronized FILM, OBAN and TRAM files are required for cut scenes. Not to mention sound files for dialog.

==The master XML file==
''The project file for level creation.''

The '''master XML''' file's '''name determines''' the '''BSL folder name''' and the '''AKEV and ONLV file names''' in the output folder. File paths in the XML can be either absolute or relative.

'''Mandatory files''' for level import:
* ''level_environment''.dae
* ''level_bnv''.dae
* ''level_textures.tga/jpg/png''
* Character.xml or AISA with player
* ONSK name in <Sky> (in Windows, this can be a fake name; does the Mac need actual ONSK files?)
* ONLD file for the new level; read [[Making_a_mod_package#Mod_Info.cfg|HERE]] about making sure your level is unlocked (accessible on the Load Game screen)

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
|valign="top"| <Level SharedPath="...">
|valign="top"| link
| The master XML file can link to other XML files. Most of them will be [[OBD:BINA/OBJC#OBJC_types|BINACJBO]] files. The file type is declared inside the file, so the file name itself doesn't have to contain the type. Ergo, "BINACJBOCharacter.xml" can be given a simpler name like "Character.xml".

Some resources used by those XML files can be found in a '''shared''' folder. OniSplit copies textures and "physics" objects into the output folder; furniture objects will be integrated into the AKEV. Unused resources in the shared folder will be ignored. That way the final level archive or AE package contains only the necessary files, saving disk space for the end user.

In the demo are various subfolders in the '''shared''' folder: consoles, doors, furniture, triggers and turrets. These file types do not need their file prefixes: CONS, DOOR, TRIG and OFGA. OniSplit will recognize them nonetheless.

'''Common mistake:'''

CJBO files '''need relative paths to the resource instead of just file names'''. Taking consoles, for example: a standard export to XML gives you "console_data". But to use the shared resources these must be paths like "'''consoles/console_data.oni'''" as they are stored in '''shared/console/'''. Note how the demoed '''shared''' folder is placed next to the [http://mods.oni2.net/node/299 project ("lab")] folder and the XML master file points to it using "../shared".
|-
| <Environment>
| -
|
|-
| <Model>
| -
| Used to import level geometry and static objects. See [[#<Model>|HERE]] for detailed information.
|-
| <Import Path="..."/>
| link
|
|-
| <Node Id="...">
| string
| informational (space for notes)
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Can be used with BSL commands such as ...
: [[#<Model>|env_show ID 1]] (use 0 to hide)
: [[#Breakable glass with BSL recognition|env_broken ID1 [ID2]]] (if a second ID is supplied then objects in the range ID1..ID2 get counted; "3001 3018" would cover 18 objects)
: [[#Texture exchange|env_texswap ID texture]] (no file prefix/suffix allowed)
: [[#env_shade|env_shade ID ID R G B]]
Static objects store their ID in [[XML:AKEV#IDXA_.28quad_group_id.29|one of AKEV's IDXA instances]].
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
|valign="top"| <Rooms>
|valign="top"| -
| For detailed information see [[#<Rooms>|HERE]].

For a Google SketchUp BNV tutorial see [http://oni.bungie.org/forum/viewtopic.php?pid=36760#p36760 HERE].
|-
| <Import Path="..."/>
| link
| File path to *.dae file. BNV data, used to create pathfinding.
|-
| <Textures> {{Anchor|textures_tag}}
| -
| With OniSplit v0.9.94.0+ you can use attributes to set the default import formats and max dimensions. For example:

: <Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">

Textures with a dimension that isn't a power of two (2x) and textures larger than 512px on a side will be resized. For example, 2003x2000 will become 512x512. (What would 257x255 become?)
|-
| <Texture Name="...">
| string
| TXMP file name to generate.
|-
| <Flags>
| flag
| Optional tag. For list of flags see [[XML:TXMP|HERE]].
|-
|valign="top"| <Format>
|valign="top"| flag
|
:DXT1
:BGR
:RGBA
:BGR555
:BGRA5551
:BGRA4444
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
| <Image>
| link
| File path to *.tga/jpg file.
|-
|valign="top"| <Sky>
|valign="top"| string
| ONSKfile.oni (without file pre- and suffix)

The import doesn't work with an empty tag. <Sky>clear</Sky> helps here; any other fictional name will also do.

For detailed information see [[XML:ONSK|HERE]].
|-
| <Objects>
| -
|
|-
|valign="top"| <Import>
|valign="top"| link
| File path to an OBJC (collection) file. Supported collection files for <Import> are:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[#Furniture.xml|Furniture.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[#Physics.xml|Physics.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

The following two collection files are '''NOT''' supported. You need to copy them as regular pre-compiled *.oni files into your mod package:
: [[XML:BINA/OBJC/MELE|Melee.xml]] (overrides global MELE; not used in vanilla levels)
: [[XML:BINA/OBJC/CMBT|Combat.xml]] (overrides global CMBT?; not used in vanilla levels)

'''Inside''' the following three supported collection files, provide links to pre-compiled (*.oni) class files: console, door and furniture collections. Use relative paths such as:
:: <code>'''consoles/'''console_data'''.oni'''</code>
:: <code>'''doors/'''TCdouble'''.oni'''</code>
:: <code>'''furniture/'''V_tctf_bigvan'''.oni'''</code>

When you are unsure about the folder structure refer back to the [http://mods.oni2.net/node/299 level import demo].
|-
| <Films>
| -
|
|-
| <Import>
| link
| File path to *.xml file. OniSplit creates a [[XML:FILM|FILM]] file from it. Used for characters in cutscenes.
|-
| <Cameras>
| -
|
|-
| <Camera Path="...">
| link
| File path to *.dae file. OniSplit creates an OBAN file from it. Used for cutscenes.
|-
| <Animation Name="..."/>
| string
| Name for the OBAN file.
|}

This is a trimmed-down version of the master file '''lab.xml''' from the demo. It's meant to give you a first impression. We might upload a smaller demo someday with all features nonetheless.

<?xml version="1.0" encoding="utf-8" ?>
<Oni>
<Level SharedPath="../shared">
<Environment>
<Model>
<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_bomber_window.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>
</Model>
<Rooms>
<Import Path="env/lab_bnv.dae"/>
</Rooms>
<Textures>
<Texture Name="GOO">
<Format>bgra4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>
</Environment>
<Sky>sunset</Sky>
<Objects>
<Import>Character.xml</Import>
<Import>Furniture.xml</Import>
<Import>TriggerVolume.xml</Import>
<Import>Physics.xml</Import>
</Objects>
<Films>
<Import>films/BomberKonRun01.xml</Import>
<Import>films/BomberKonRun02.xml</Import>
</Films>
<Cameras>
<Camera Path="cameras/BomberCam01.dae">
<Animation Name="BomberCam01"/>
</Camera>
<Camera Path="cameras/BomberCam02.dae">
<Animation Name="BomberCam02"/>
</Camera>
</Cameras>
</Level>
</Oni>

===<Model>===
This tag is mandatory (it must be present to avoid errors); the model section contains one import path to the AKEV (level) geometry (*.dae) and can contain additional import paths for exceptions (*.dae).

Data from the demo:

<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>

'''env_show'''

The motorcycle has here scripting ID 9. You can show and hide the object with the BSL command '''env_show''', where the second parameter means true or false. '''Never use 0 as an ID''' because it won't work.

env_show 9 1
env_show 9 0

EdT demonstrates env_show [https://www.youtube.com/watch?v=Em6wa5JTQNM here]. Note how the objects have collision.

The last vanilla level (Syndicate Mountain Compound) has a big satellite dish platform that can be made hidden. Obviously, such objects/areas can be made to have pathfinding too.

;More possible applications of env_show:
* ground/ceiling/objects for cutscenes that become partially destroyed
* destructible walls like in Deus Ex: Human Revolution (trigger volume, replacing punch anim with punch-through-wall anim)
* grids in front of ventilation shafts (a small door object could be an alternative)
** at the moment this can't be done because characters can't sneak under the top edge of the opening (the characters collision spheres are too big)
* managing object groups with trigger volumes (save multiple objects in one DAE file)



====Import of object groups====
'''Mod Tool versus SketchUp'''

The meaning and behavior of "groups" greatly differs in these two programs.

:'''In SketchUp''' you can group objects which enables you to easily duplicate all objects inside a group and to scale/rotate/translate them all together.

:'''In Mod Tool''' grouped objects are still loose, and duplicating a group won't duplicate the objects. To achieve the same effect as in SketchUp, you have to create a hierarchy where any one object is the "parent" and all others the "children".

'''Google SketchUp'''

To create a group, select two or more objects, right-click on the selection and choose "make group".

[[Image:ModTool_can_import_objs_in_hierarchies.jpg|right|thumb|Mod Tool can import objects in hierarchies to Oni.]]
'''Mod Tool'''

Either use the Explorer (A) or the Schematics (B) to create a hierarchy.

:(A) In the Explorer window, drag and drop one or more objects onto another one.

:(B) Open the constrain tab at the right side. Select parent object, click "Parent", click the child object(s). Check the result in the Schematics window.

:'''Mod Tool: caution when saving to DAE!'''

:A normal selection won't do. You have to select the object tree to successfully save a hierarchy. This is the same way that you do it with Oni characters.


====Breakable glass with BSL recognition====
Broken environmental objects can be recognized by the BSL command ''env_broken (ID_1, ID_N)''. However, this requires additional code to work.

An example is the training level. Let's determine how we can set up such a thing.

First we need a [[XML:BINA/OBJC/TRGV|trigger volume]] like in level 1.

<TRGV Id="11495">
<Header>
<Flags>Locked</Flags>
<Position>-714.6615 -298 -555.2073</Position>
<Rotation>0 0 0</Rotation>
</Header>
<OSD>
<Name>tv75</Name>
<Scripts>
<Entry></Entry>
<Inside>targets_gone</Inside>
<Exit></Exit>
</Scripts>
<Teams>255</Teams>
<Size>400 31 270</Size>
<TriggerVolumeId>75</TriggerVolumeId>
<ParentId>0</ParentId>
<Notes></Notes>
<Flags>PlayerOnly</Flags>
</OSD>
</TRGV>

Now we need some BSL code.

var int inside_target_function;

func void enter_target_function(void)
{
dprint enter_target_function
inside_target_function = 1;
}

func void exit_target_function(void)
{
dprint exit_target_function
inside_target_function = 0;
}

func void targets_are_not_gone(void)
{
# CB: turn off the trigger volume and sleep for a second
# so as not to cause hideous performance loss
trigvolume_enable tv75 0
sleep 60
trigvolume_enable tv75 1
}

func void targets_gone(string ai_name)
{
if (inside_target_function eq 0)
{
enter_target_function() # catch other "targets_gone" functions to let them do nothing

var int num_broken = env_broken(3001, 3018);
# if you only one target use scheme: env_broke(3001, 3001)

if (num_broken eq 18)
{
targets_are_gone();
}

if (num_broken < 18)
{
targets_are_not_gone(); # to set check interval to one second
}

exit_target_function
}
}

func targets_are_gone
{
trigvolume_enable tv75 0
# [...]
}

;Explanation:

Player enters the TV, targets_gone() gets triggered. The variable "inside_target_function" should be 0 by default, so we will enter the "if" block. Next, we can assume that the player didn't destroy all glass objects, so "num_broken" will be less than 18; thus, targets_are_not_gone() gets called.

The TV function targets_gone() ''would'' be triggered every frame, but targets_are_not_gone() creates a delay between checks: the TV gets deactivated for 60 frames. Then the TV becomes enabled again and will start anew until all glass objects got destroyed or player left the TV.

In this case the targets_gone() function will do nothing because "inside_target_function" was set to 1 by the first call.

targets_are_gone() eventually disables the TV to prevent memory overflow; this function also contains all the things ("[...]") that you want to happen after the glass target is broken.

====Texture exchange====
BSL command supported on Windows and Mac:
: env_texswap ID texture

Might be useful to switch on/off static and animated textures. (News broadcast screen: running or off or smashed. Lava stream: flowing or stagnating or cooled down. Etc.)

A similar effect can be achieved by showing/hiding geometries with different textures as EdT has demonstrated in a private test. That way it should also be possible to have different vertex coloring for an area.

====Vertex coloring====
Vertex colors can be edited manually in Blender by setting up following 3 things:
* Properties Panel > Data > Color Attributes
* 3D viewport (left top) > change work mode to Vertex Paint
* 3D viewport (right top) > change to Viewport Shading to Solid mode (under the dropdown menu you can choose "flat" to have full saturation)

{{divhide|Mod Tool}}

[http://web.archive.org/web/20170529111607/http://softimage.wiki.softimage.com/xsidocs/tex_vcolor_CreatingColoratVerticesCAVMaps.htm SoftImage documentation.] Observation: The sniper tower from level 19 Syndicate Mountain Compound can be isolated and re-imported as it is. It will appear quite dark.

If we remove "_color" from the object, the shadows will be gone next time we import the tower.

Mod Tool: Explorer [8]

Object
|
+-- Polygon Mesh
|
+-- Cluster
|
+-- Polygon
| |
| +-- [...]
|
+-- NodeProperties
|
+-- '''_color'''
+-- texcoord (Explicit UVWs)
|
+-- Vertex_Color_Def

So, how do we modify that data?

'''Single object shading'''

If there's already a vertex color property, you can use Shift + W to activate the Paint Vertex Color Tool. With Control + W you can change the brush color. R + Hold Click + Move Mouse let you change the brush size. The more vertices (points) you have, the more detailed you can make the shadows/colors. But keep in mind that too many polygons can destroy collision, making characters fall through the ground.

If there's no vertex color property, the first usage of Shift + W will create that property. But you can also manually create it via Property > Color under Vertices Map.

'''Level-wide shading'''

[[Image:light_test_modtool.png|right|thumb]]
[[Image:light_test_ingame.png|right|thumb]]

To get general shading/lighting you can set up light sources. "Infinite" lights are useful for global lighting, while "Light Box", "Point", "Neon" and "Spot" are more suitable as local light sources. They can be accessed via Primitives > Light.

By default, a Mod Tool scene has one Infinite light, but it doesn't shine in every direction so you might want to add more Infinite lights. Let's say one Infinite light for each direction (+X, -X, +Y, -Y, +Z, -Z) with an intensity of circa 0.25 (night) or 0.75 (day).

The illumination of those lights can be integrated into the vertex color property. There's some information [https://web.archive.org/web/20201029114108/http://oni.bungie.org/forum/viewtopic.php?pid=29089#p29089 on OCF here]; the quoted information is in triplicate, so don't get confused by that: at first it's detailed, then summarized, then as a checklist.

Basically, you can go with the checklist:

* Property > Color At Vertices Map
* Property > Render Map
* In render map property page, under Sampling select Vertices Only
* Under Surface Color, choose Enable, then in the box below select Vertex _Color; if that option does not appear, click on the New button next to it
* Under Map, select Illumination only
* Finally, click on the button Regenerate Maps...

This must be done for all objects separately.

: [http://mods.oni2.net/system/files/vertex_color_script.txt There's a script here] which can apply vertex color and render maps to all '''selected''' objects. Load it into the script editor with Alt + 4 and hit F5 to run it. (Be sure the script's language was set to VBScript.)
: The variable "overwrite_VC" can be changed.
:: With "1" all existing CAV maps of selected objects will be overwritten. This can take some time.
:: With "0" only selected objects without CAV maps will be the script's target.

'''Notes on ModTool view modes'''
* "Constant" let you see the colors of the vertex coloring only.
* "Textured Decal" let you see object textures only.
* "Shaded" let you see the illumination only.
* "Textured" let you see the textured object with illumination and vertex coloring.
{{divhide|end}}

=====env_shade=====
If you use '''env_shade''', use it with caution. It completely overwrites the vertex coloring.

# BSL command
# env_shade obj_id obj_id R G B

# examples
env_shade 7 7 # object 7 will be black
env_shade 7 7 0 0 0 # object 7 will be black
env_shade 7 7 .31 .999 .5 # object 7 will be quite green
env_shade 7 10 1 1 1 # object 7, 8, 9, 10 lose all their shading

====Baked lightmaps====
A drawback of this method, AKA shadow maps, is the high number of [[XML:BINA/TMBD|TMBD]] changes and new textures for every wall, requiring a lot of memory. How to create shadow maps:

* https://web.archive.org/web/20121105081823/http://www.game-artist.net/forums/support-tech-discussion/5622-burning-shadows-onto-texture-xsi.html


Notes on map options:
* "Surface color and illumination": outputs used texture with added shadows
** Can be used to replace original texture
* "Illumination only": output a texture that only contains the shadows
** Can be used on a new overlying, transparent surface

====Standalone lightmaps====
With this approach there are two meshes, whereby the shadow effects on one mesh get drawn in front of the regular level texture.

Compared to the "baked lightmaps" method, this needs more polygons of course. And these polygons are transparent, which is a problem with Oni's limited rendering ability for such textures. However, standalone lightmaps only need a few new textures if used wisely.

Read [[Lightmapping levels]] to learn more.

[[Image:Oni_Lightmaps_double_polygon_method.jpg|center]]

===<Rooms>===
The Rooms tag is mandatory. It contains an import path to BNV and ghosts (*.dae) which are used to create pathfinding grids. For information on the binary data behind this, see [[OBD:AKVA|HERE]].

Sample code from the master XML file:
<Import Path="env/lab_bnv.dae"/>

'''Fundamentals'''
* '''BNVs''' are '''volumes''' (sometimes also named '''rooms''') that have a pathfinding grid assigned to them.
* For practical reasons you only need '''floors and ramps''' to build a BNV. (As seen [http://edt.oni2.net/images/Hideout_BNV.jpg HERE.])
** A BNV polygon can consist of 3 or more points, but it's recommended to use '''shapes with 4 points''' because the other shapes usually waste more grid space. At the moment you can import only '''[[wikt:convex|convex]]''' shapes.
* Secondly, there are so called '''ghosts''' (vertical quads) that connect '''neighboring BNVs'''. AI can only transit from BNV to another through ghosts.
: OniSplit gives error messages for ghosts that don't have 2 neighboring BNVs, for example:
BNV Builder: Ghost 'grid2' has no adjacencies at <-72,41 1,999 -166,6> and <-71 1,999 -168,21>, ignoring

'''Tolerance values'''
* Horizontal distance from room to ghost: 1
* Vertical distance from room to ghost: 18
* Ghost's horizontal dimension must be greater than 0
* Under optimal circumstances, pathfinding works on a plane that is +4 world units above or -0.5 below the pathfinding grid
* Normally characters can't pass over low vertical walls such as stairs/curbs if those don't have a ramp under them; near ground level (Y=0) is an exception where characters are allowed to step on a plane that is 4 world units above pathfinding grid; higher planes need a ramp
* Maximum angle of ramp you can go on is 70°; higher angles will make characters fall through to their death (in those cases you might want to add invisible walls/boxes to prevent them from touching the ramp)

'''More notes on PF processing'''
* Actually, BNV and ghosts can have any name and don't need any texture.
* During pathfinding calculation, OniSplit creates a new folder called "temp" and a subfolder "grids". There is a file named "''levelname''_grids.dae". That file contains rooms with textures called "bnv_grid_''N''.tga" which mark obstacles in the pathfinding grid. Ghosts will have a transparent texture "'''_marker_ghost'''.tga". You also get these when you export a level. Transparent ghosts make it easier to see the rest of your level if you have many of those planes.
* In Mod Tool, ghosts and rooms can be grouped under a null object. Right-click the null object to select all its children, then use "Selection Only [x]" as your saving option. That way all the planes can be quickly saved to a *.dae file.
* You can influence the pathfinding creation of dangerous zones using danger quads. Read about those [[#Marker textures|HERE]].
* Another kind of influence is the [[#<Model>|gunk flag]] IgnoreGrid. It can be used to tell OniSplit to ignore the object during pathfinding creation. The grids in that place will be white.

[[Image:Pathfinding_grid.jpg|thumb|200px|right|'''ai2_showgrids = 1''' in action]]
'''BSL commands'''
* chr_show_bnv = 1
:: shows number of BNVs the player is standing on
* ai2_showgrids = 1
:: shows pathfinding grids
* ai2_chump
:: spawns a friendly Striker that follows the player if possible, makes also pathfinding grids visible
* ai2_chump_stop = 1
:: Striker stops following you
* ai2_chump_stop = 0
:: Striker follows you again

====Pathfinding on uneven ground====
Pathfinding works on slightly uneven ground as long as the polygons are 0.5 world units beneath or 4 world units above the BNV.

For greater surface irregularities, we can use a trick:
* The problematic polygons must be saved to a DAE file and then referenced in the model section as an individual object.
* Then the <GunkFlags> tag needs to be '''''GridIgnore'''''.
* Additionally we create a plane (invisible if necessary) under the object so that Oni doesn't think there's a hole.
* The ghosts must be taller than the highest polygon to be walked on. (This has been tested up to a height of 2,000 world units.)

'''Symptoms of too-small ghosts'''

A) AI can't run at all.

B) AI loses PF ability if the tracked enemy performs animations that are outside of the pathfinding volume. Here's a video (<nowiki>https://youtu.be/vfKPzP5hiCo</nowiki>, dead link) showing these symptoms.

'''Missing boundaries'''

Let's say you have a BNV, tall ghosts, and a GridIgnore-flagged hill with trees and bushes and stuff.

Why do AIs run up against the trees?
: '''Problem:''' There are no red/orange grids that limit the AI's movement. Normally, objects will produce red pathfinding squares around them. But objects that are 20 world units above the BNV are ignored just like objects with the IgnoreGrid flag.
: '''Solution:''' Add simple geometries like ''_marker_impassable fences'' or danger quads near the BNV.

'''Disappearing AIs'''

The ground is sometimes not solid, and the player and AIs are falling through it.

: '''Problem:''' On GridIgnore-flagged uneven ground, AIs can fall through it when they are out of the player's view.
: '''Solution:''' Use either '''chr_lock_active ''AI_name''''' or '''chr_all_active = 1'''

====Debugging====
'''(OniSplit v0.9.93.0+)'''
[[Image:OniBrowser.jpg|thumb|200px|right|OniBrowser displaying level geometry plus PF and ghosts.]]

* '''env_show_ghostgqs = 1''' makes the ghost quads visible
** The original ghost quads can't be seen; per Neo, "they are not included in the octtree and bsp tree"
** To see them you must use the -debug option in the level creation command (available with OniSplit '''v0.9.93.0+''')
OniSplit.exe -create:level ''output_folder'' '''-debug''' ''input_folder''/''master_xml_file''.xml

Not all debugging/testing needs to be done in Oni. There is also a [http://mods.oni2.net/node/256 program] (Windows only) which can display the whole level.

For example you can load an AKEV*.oni, select the level name, and use the hotkeys [B] and [P] to display BNVs and ghosts.

'''Bug prevention:'''

After all testing is done, you should compile the level a last time without the -debug option.

AIs appear to have trouble shooting through ghost quads that got registered in the octtree/BSP tree as seen here (<nowiki>https://www.youtube.com/watch?v=-ZugVBgBVKc</nowiki>, dead link).

====When OniSplit fails to connect PF quads====
[[Image:Pathfinding_creation__merge_polygons_to_fix_connections.jpg|thumb|200px|right|Fixed PF in compound level after underground construction...]]
It can help to merge polygons to one object and merge their edges. These become white. (Outer edges are blue.)

===<Textures>===
====...used for exceptions====
The [[#textures_tag|textures tag]] is mandatory.

AKEV textures will be imported by the master XML file automatically; you don't need to add them to that file.

: With OniSplit v0.9.82-93.0, the textures' formats will be DXT1 and (for transparent ones) BGRA4444.
: With OniSplit v0.9.94.0+ the textures' formats will be BGR and (for transparent ones) RGBA.

To change the default texture import format, use the Texture'''s''' tag. (Possible with OniSplit v0.9.94.0+.)

To change the format/flag/gunk flag of a specific texture, use the Texture tag.

An example:

<Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">
<Texture Name="GOO">
<Flags>TwoSided</Flags>
<Format>BGRA4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>

* Use the gunk flag "TwoSided" to make surfaces visible from both sides.
* If the texture comes with the gunk flag "NoCollision" then all objects with that texture will have no collision. Characters would fall through it.

Transparency and no collision together would make sense for a water-like substance. The Vago Biotech level uses this approach for the area with green toxic waste.

[[Image:making_a_surface_transparent_and_twosided.png|thumb|200px|right|'''Figure 1''']]

[[Image:AKEV_single_object_multiple_textures.png|thumb|200px|right|'''Figure 2''' one object with multiple textures, one per polygon cluster]]
[[Image:AKEV_single_object_multiple_textures_ingame.png|thumb|200px|right|'''Figure 3''' blue: two-sided glass: two-sided and transparent random metal: no flag (one-sided)]]

'''TwoSided and transparent objects'''

It's also possible to set this in Mod Tool. For TwoSided-ness, use one image source for diffuse and transparency. (It won't work with two image sources even if both sources use the same image.)

For transparency you must additionally use the three checkboxes:
* Transparency: Enable
* Transparency: Use Alpha
* Transparency: Invert

See '''Figure 1'''.

====Regular textures====
OniSplit automatically imports textures of objects in the [[#<Model>|<Model> section]]. Those objects could be considered as AKEV core geometry.

'''One texture per object'''

Furniture and Physics objects are allowed to have only one texture per object. AKEV core geometry can have one texture or multiple textures – that's up to you to decide.

'''Multiple textures per object'''

'''Question:''' How do we apply multiple textures to an AKEV core object?

'''Answer:''' Assuming you are using Mod Tool the procedure will be as follows. Repeat this for each cluster you create (except for projection). See also '''Figure 2 and 3'''.

* Select some polygons
* Go to Material > Phong
* Hit [7] to open Render Tree
* Add a texture and connect "Image" with "Phong", choose "diffuse" as illumination mode
* Double-click "Image" to open Material page
* In the Texture Projection section, click on "New" and choose a suitable projection
** Do this only if there isn't a projection in the "Texture_Coordinates_AUTO" cluster yet
** OniSplit processes only one texture projection, see '''Figure 4'''
* Choose the texture and UV, then fine-tune the UV via Alt + 7

[[Image:AKEV_multiple_textures_one_projection.png|thumb|200px|right|'''Figure 4''' use only one texture projection per object]]

Caution: textures will be fixed to one set of flags. You can't use the same texture A for a one-sided cluster/object B and a two-sided cluster/object C. You would need to create a differently-named clone of that texture and apply that to cluster/object C.

====Marker textures====
Marker textures are used to import certain objects with special flags. Import those objects alongside [[#<Model>|AKEV core]] geometry.

Marker textures aren't imported automatically. Add those textures to the final package or plugin yourself, e.g. with some sort of script.

OniSplit.exe -create:txmp out env/markers/*.tga

The flags Transparent, TwoSided and NoOcclusion are only set if the same texture source is used for diffuse and transparency and if transparency setting are enabled. See the subsection under "[[#...used for exceptions|...used for exceptions]]" called "TwoSided and transparent objects".

'''Danger quads'''

Pathfinding grids have different colored squares with different meanings.
* white/gray - clear space
* green light - near wall
* green - semi-passable
* green dark - stairs
* blue very light - border 1
* blue light - border 2
* blue - border 3
* blue dark - border 4
* '''orange - danger'''
* red - impassable

For detailed information on colors, see [[OBD_talk:AKVA/0x24#EFFECTS_of_various_pathfinding_grid_tile_types|HERE]].

Normally, OniSplit decide how to color the grids. But it's possible to add your own danger quads to fine-tune zones of higher danger. Those orange areas will be generated with the 4 different blue borders around it.

Danger quads must have "'''_marker_danger'''" as texture name.

Results in flags: Transparent TwoSided NoCollision Invisible NoOcclusion Danger

'''_marker_barrier'''


Results in flags: Transparent TwoSided(double-check) Invisible NoObjectCollision NoOcclusion

'''COLLISION (boxes)'''

AIs can get stuck in detailed geometry. This can be prevented with collision boxes. In-game the box will be invisible, but has collision so characters can't get through. The pathfinding grid will be red where it comes in contact with the box; the red is followed by a light green and then regular green.

[[XML:OFGA|OFGAs]] use the COLLISION texture. Onisplit doesn't automatically apply gunk flags to it. You need to use XML tags for that. Typically it would be <GunkFlags>Invisible NoObjectCollision</GunkFlags>

'''Stairs'''

Texture: '''_marker_stairs'''

Normally, characters can't move on stairs because they contain vertical rises. In this case you can use a sloping quad that is above or inside the staircases. It's possible to set the desired flags in the <Model> section, but doing so and exporting these self-made stair ramps is wasted time. Simply apply _marker_stairs to that quad and characters will be able to move on that surface.

Resulting flags: Stairs Transparent TwoSided Invisible NoObjectCollision NoOcclusion

This has no effect on pathfinding creation. Regularly-textured stair geometry (which intersects the marker quad) will be flagged as NoCharacterCollision.

'''Impassable'''

texture: '''_marker_impassable'''

Resulting flags: Transparent TwoSided (<-double-check this) Invisible NoOcclusion

Impassable walls are very similar to collision boxes except that particles can also collide with them. The pathfinding grids will be also red, light green, and green.

'''Blackness a.k.a. jello fix'''

Texture: '''_marker_blackness'''

Resulting flags: TwoSided NoCollision

Simply black walls. No effect on pathfinding creation. The purpose of these walls in Oni is to block out areas outside of a level's outermost wall so that the Jello-cam cannot show the player other parts of the level when it escapes a wall. See [[Jello-cam]] for details.

'''Doors'''

Texture: '''_marker_door'''

Resulting flags: DoorFrame Transparent TwoSided NoCollision NoOcclusion

Don't use this.

===<Objects>===
Information on regular object lists can be looked up here:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

====Furniture.xml====
The AKEV core geometry is more or less the overall structure of the level while this furniture file adds standard objects (e.g. crates and desks) to it.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Objects>
| -
| This tag marks the file as BINACJBO.
|-
| <Furniture>
| -
| This tag marks the file as FURN.
|-
| <Header>
|
|
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag. Ignore it. Those flags were used in the past.
:None
:Locked
:PlacedInGame
:Temporary
:Gunk
|-
| <Position>
| float x3
| Optional tag. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag. X Y Z rotation.
|-
| <OSD>
| -
|
|-
|valign="top"| <Class>
|valign="top"| link
| File path to a '''pre-compiled [[XML:OFGA|OFGA]] (*.oni) file'''. Use it as part of a relative path. Make sure that the OFGA comes with the files it needs: M3GM and TXMP.

An OFGA can hold multiple M3GMs. That 3D content will then be integrated into the AKEV.
|-
|valign="top"| <Particle>
|valign="top"| string
| This name gets written into <Tag> inside ONLV (ENVP section) and can be used with BSL commands, e.g. you can take control over a particle via '''particle BSL_name start'''. For more commands, see [[XML:BINA/OBJC/PART#BSL_support|HERE]].

Take care with the naming of new OFGA files. The particle name will be composed of 2 parts separated by an "_" underscore. When one tag is empty, the final name will contain an underscore nonetheless. '''Examples:'''

: FURN <Particle>test</Particle> + OFGA <Tag>streetlight</Tag> = '''test_streetlight'''
: FURN <Particle></Particle> + OFGA <Tag>streetlight</Tag> = '''_streetlight'''
: FURN <Particle>test</Particle> + OFGA <Tag></Tag> = '''test_'''
|}

;Example

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Objects>
[...]
<Furniture>
<Header>
<Flags>Gunk</Flags>
<Position>-62.692 -29 108.35</Position>
<Rotation>181.522 356.021 178.114</Rotation>
</Header>
<OSD>
<Class>furniture/V_tctf_bigvan.oni</Class>
<Particle></Particle>
</OSD>
</Furniture>
[...]
</Objects>
</Oni>

====Physics.xml====
This file is for objects with "physics". Unlike AKEV core geometry or furniture, these objects can be animated.

: A small video tutorial on [https://www.youtube.com/watch?v=CFNseg_2UxA how to create a simple animated object]

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Physics>
| -
|
|-
| <Object Name="...">
| string
| Use a unique name for each object.
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Tested with BSL command...
:obj_create ID [ID]
:obj_kill ID [ID]
:env_anim ID [ID]
:env_setanim ID [ID]
The scripting ID will be stored in the ONLV's OBOA instance.
|-
|valign="top"| <Flags>
|valign="top"| flag
|
;Object setup flags
:None
:InUse
:NoCollision
:NoGravity
:FaceCollision
|-
|valign="top"| <Physics>
|valign="top"| flag
| Optional tag for an Object.
:None
:Static
:Linear
:Animated
:Newton (used with <Flags> FaceCollision to [https://www.youtube.com/watch?v=YICB7qugrtc make an object pushable])
:: For a pushable object don't use import sub-tags such as animation name, flags, etc. Just use <Import Path="..." '''/'''> or <Import Url="..." '''/'''>
|-
| <Position>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z rotation.
|-
| <Scale>
| float
| Optional tag of Object. Only used for non-animated objects.
|-
|
<Import Path="...">

<Import Url="...">
|valign="top"| link
|valign="top"| This tag comes in two variants. It doesn't matter what variant you use.
|-
| <Animation Name="...">
| link
| File path to *.dae file.
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag of Animation. For more information on those flags look [[XML:OBAN|OBAN]] page.

;Object animation flags
:None
:Loop
:PingPong
:RandomStart
:AutoStart
:Local
|-
| <End>
| integer
| Optional tag of Animation. Frame number. Used to define the end of an OBAN from a *.dae file.
|-
| <Start>
| integer
| Optional tag of Animation. Frame number. Used to define the start of an OBAN from a *.dae file.
|}

The XML code for physics can be written in two styles.
*The '''first style''' mimics the original structure found in extracted ONLV instances. This makes it '''easier to edit old levels and reimport them''' into the game.
*The '''second style''' was created with structured data (nested objects) in mind and is '''suited for totally new levels''' where animated objects must be created in a 3D editor at first.

'''Code style 1'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
<Object>
<Geometry>M3GMDishBase.oni</Geometry>
<Animation>OBANDishBase.oni</Animation>
<Physics>Animated</Physics>
<ScriptId>201</ScriptId>
<Position>-197.729141 128.46283 -2501.46387</Position>
<Rotation>0.7071067 -1.545431E-08 1.545431E-08 0.7071068</Rotation>
<Scale>2.109375</Scale>
<Name>object_DishBase</Name>
</Object>
</Physics>
</Oni>

'''Code style 2'''
:For documentation purposes, the file here has been trimmed down.

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
[...]
<Object Name="motorcycle">
<ScriptId>8</ScriptId>
<Flags>FaceCollision</Flags>
<Import Url="motorcycle/export.dae">
<Animation Name="motorcycle02">
<Flags>AutoStart</Flags>
<End>880</End>
</Animation>
<Animation Name="motorcycle02_stop">
<Start>881</Start>
</Animation>
</Import>
</Object>
[...]
</Physics>
</Oni>

In this example, OniSplit takes the file "export.dae", looks at the parts it contains, and creates geometry files from it.
* M3GMhubs_rear.oni
* M3GMhubs.oni
* M3GMmotorcycle.oni
It's convenient that hierarchies are supported here.

The motorcycle is made of 3 parts so 3 object animations ([[XML:OBAN|OBAN]]) will be created up to frame 880. Then OniSplit creates 3 more OBANs starting from frame 881.

The reason for the interruption at frame 880 is probably to give Barabas a little more camera time in the cutscene.

;Notes about BSL usage:

The Vago Lab cutscene script uses the motorcycle objects and animations like this:
env_show 8 0 # hide static motorcycle parts or else they would be visible
env_show 9 0 # while Konoko is still riding her animated motorcycle
env_show 10 0 # the static motorcycle is separated into objects 8, 9 and 10

# Static and animated objects are totally independent from each other.
# They are stored in different arrays so their script IDs can use the same numbers.

obj_create 8 10 # create all animation-ready motorcycle parts
env_anim 8 10 # animate those parts (not necessary if OBAN flag is "AutoStart")

# The first animations would loop because of "AutoStart", so get the
# right timing to apply the other animations. "motorcycle02_stop"
# and the others will not loop because they don't have "AutoStart".
env_setanim 8 hubs_stop
env_setanim 9 hubs_rear_stop
env_setanim 10 motorcycle02_stop

obj_kill 8 10 # delete all animated parts
env_show 9 1 # show static motorcycle model where Konoko parks her bike

====Corpses.xml====
An empty Corpse element (<Corpse />) is treated as unused and placed at the end of the array. If no such empty elements are provided, OniSplit automatically adds 5. OniSplit also ensures that there are at least 20 corpses in the array.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Corpses>
|
|
|-
|valign="top"| <Corpse>
|valign="top"| -
|
|-
| <Class>
| link
| [[XML:ONCC|ONCC]]''name''
|-
| <Transforms>
| -
| There are 19 <Matrix> for each <Transforms> (which represents a body part).
|-
| <Matrix>
| matrix
| Float 3x3 + float x3 for the last 3 values (X Y Z position). For more information about the matrix, see [[OBD:CRSA]].
|-
| <BoundingBox>
| -
| Bounding box of the whole corpse. Optional; if not provided, OniSplit will generate an approximate one. Currently it doesn't try to locate the ONCC to compute an exact bounding box.
|-
| <Min>
| float x3
|
|-
| <Max>
| float x3
|
|}

'''Trimmed example'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Corpses>
<Corpse>
<Class>generic_male_1</Class>
<Transforms>
<Matrix>-0.36488995 0.04620622 -0.9299034 -0.05580434 -0.9980576 -0.02769538 -0.9293768 0.04178688 0.366759717 -215.667755 1.603917 92.85312</Matrix>
<Matrix>0.2961557 -0.185628444 0.936928 -0.368288517 -0.9272724 -0.06730227 0.8812806 -0.32512787 -0.342981815 -216.51889 1.64218426 93.189</Matrix>
<Matrix>0.407847315 0.156575248 0.8995248 -0.238757968 -0.9326179 0.2705892 0.8812805 -0.3251278 -0.342982143 -215.239883 0.8405094 97.23532</Matrix>
<Matrix>0.439697325 0.467113584 0.767118752 0.0248355754 -0.8601105 0.5095029 0.8978026 -0.204975232 -0.389789373 -213.6234 1.46109009 100.80056</Matrix>
<Matrix>0.717241049 -0.179043233 0.673430443 0.4761817 -0.579636 -0.6612664 0.5087397 0.794962764 -0.3304816 -214.81662 1.56564879 92.5172348</Matrix>
<Matrix>0.3398023 0.1672905 0.925498843 0.7910236 -0.5831365 -0.185023025 0.5087395 0.7949628 -0.330481827 -211.71907 0.792413354 95.42558</Matrix>
<Matrix>0.1283634 0.227430075 0.965297 0.804142356 -0.59352535 0.032904774 0.5804117 0.7720126 -0.259073079 -210.372269 1.45546341 99.0937653</Matrix>
<Matrix>-0.285799921 0.06851995 -0.955836535 -0.240357026 -0.970681965 0.00228381017 -0.927656651 0.230394751 0.2938901 -216.284851 1.5839076 91.29168</Matrix>
<Matrix>-0.312039882 0.04875436 -0.948817253 -0.176752359 -0.9842264 0.00755515043 -0.9334825 0.1700632 0.31573534 -216.689789 1.68287766 89.9359055</Matrix>
<Matrix>-0.356412441 -0.5390179 -0.763170958 0.0404523835 -0.82494843 0.5637587 -0.933452547 0.170058519 0.315826446 -217.422012 1.7979821 87.70907</Matrix>
<Matrix>-0.101782769 -0.247171819 -0.9636112 0.5426916 -0.8256094 0.154451028 -0.8337422 -0.507223248 0.2181709 -217.747284 1.30605173 87.0125656</Matrix>
<Matrix>-0.8154478 -0.150626346 0.558888733 -0.1200991 0.9885643 0.09119747 -0.566234052 0.00724477554 -0.8242127 -217.7402 2.065678 88.15346</Matrix>
<Matrix>-0.4593738 -0.326781839 0.825947642 0.8874048 -0.1284554 0.442732215 -0.0385793857 0.9363295 0.348996729 -219.093979 1.81561315 89.08131</Matrix>
<Matrix>-0.9545983 -0.13777709 0.26412034 0.295387268 -0.322961926 0.899134 -0.0385792255 0.9363296 0.348996431 -220.3681 0.9092429 91.37218</Matrix>
<Matrix>-0.9715769 -0.0362956524 0.233924776 0.0276728421 -0.9988148 -0.0400396362 0.2351007 -0.0324283168 0.9714299 -222.775482 0.56178683 92.03825</Matrix>
<Matrix>0.979860842 -0.192433611 0.0533096045 0.193336874 0.9810555 -0.0122905634 -0.0499345176 0.0223497637 0.9985025 -216.8387 1.90143847 87.84845</Matrix>
<Matrix>0.863898 -0.399280578 0.3070101 0.171117 -0.340619326 -0.9244986 0.4737078 0.851207137 -0.225936681 -215.211975 1.58196676 87.93695</Matrix>
<Matrix>0.4673251 -0.0255063027 0.883717656 0.746463835 -0.524209559 -0.4098731 0.4737075 0.851207256 -0.225936785 -212.815842 0.47451216 88.78848</Matrix>
<Matrix>0.216871262 -0.007893051 0.976168454 0.3751846 0.9238389 -0.0758833 -0.9012231 0.3827002 0.203315422 -211.637314 0.410188764 91.0171051</Matrix>
</Transforms>
<BoundingBox>
<Min>-219.731216 -2.258905 84.47974</Min>
<Max>-207.518463 4.49535131 104.023239</Max>
</BoundingBox>
</Corpse>
</Corpses>
</Oni>





[[Category:Modding tutorials]]

Creating a level

2025-01-22T04:05:10Z

Vortice: /* Forum tutorials on level creation */Fixed broken forum links to archive.

This page covers level creation from scratch. See [[Modifying an existing level]] if you want to change a vanilla level in the game.

==Level releases and resources==
===Fan-made levels===
{| class="wikitable sortable autosort by-column-3"
!Date
!Name
!Level number
|-
|TBA
|Oni 2 Angel Studios Tour
|32
|-
|TBA
|Green Room
|26
|-
|2019/09/16
|[https://web.archive.org/web/20240527004257/http://oniforum.bungie.org/viewtopic.php?id=2965 Omega Tournament]
|31
|-
|2016/02/13
|[https://web.archive.org/web/20160224173743/http://oni.bungie.org/forum/viewtopic.php?id=2947 AI Battle]
|7
|-
|2014/01/19
|[https://web.archive.org/web/20211202225410/http://oni.bungie.org/forum/viewtopic.php?id=2698 Wilderness Preserve]
|17
|-
|2013/09/07
|[https://web.archive.org/web/20201127180732/http://oni.bungie.org/forum/viewtopic.php?id=2656 Island]
|29
|-
|2013/07/12
|[https://web.archive.org/web/20201127175459/http://oni.bungie.org/forum/viewtopic.php?id=2640 City]
|28
|-
|2013/06/01
|[https://web.archive.org/web/20201029102326/http://oni.bungie.org/forum/viewtopic.php?id=2619 Fight Club]
|25
|-
|2012/05/12
|[https://web.archive.org/web/20220701102842/http://oni.bungie.org/forum/viewtopic.php?id=2357 Old China]
|24
|-
|2012/03/18
|[https://web.archive.org/web/20211202220454/http://oni.bungie.org/forum/viewtopic.php?id=2302 Boss Battle]
|23
|-
|2012/02/12
|[https://web.archive.org/web/20201029113554/http://oni.bungie.org/forum/viewtopic.php?id=2271 De Dust Deluxe]
|22
|-
|2012/01/23
|[https://web.archive.org/web/20201029114415/http://oni.bungie.org/forum/viewtopic.php?id=2242 Parkour Challenge 2]
|21
|-
|2012/01/16
|[https://web.archive.org/web/20211205145843/http://oni.bungie.org/forum/viewtopic.php?id=2235 Parkour Challenge]
|21
|-
|2011/07/25
|[https://web.archive.org/web/20201029103607/http://oni.bungie.org/forum/viewtopic.php?id=2001 Mini-Partenon]
|5
|-
|2011/10/03
|[https://web.archive.org/web/20201029113340/http://oni.bungie.org/forum/viewtopic.php?id=2024 Muro's Lair - Preview]
|20
|-
|2011/07/03
|[https://web.archive.org/web/20201029113724/http://oni.bungie.org/forum/viewtopic.php?id=1957 Hexagon]
|16
|-
|2011/06/23
|[https://web.archive.org/web/20201029104928/http://oni.bungie.org/forum/viewtopic.php?id=1938 Junkyard]
|15
|-
|2011/05/01
|[http://mods.oni2.net/node/178 Arena of Hurt (OZG)]
|7
|-
|2010/11/08
|[https://web.archive.org/web/20210117150652/http://oni.bungie.org/forum/viewtopic.php?id=1736 Arena of Hurt (OTA)]
|7
|-
|2010/11/06
|[https://web.archive.org/web/20201029105217/http://oni.bungie.org/forum/viewtopic.php?pid=50565#p50565 Martian Colony] AKA "Silly World"
|5
|-
|2010/02/15
|[https://web.archive.org/web/20201029113916/http://oni.bungie.org/forum/viewtopic.php?id=1506 Maze]
|5
|-
|2008/09/16
|[http://mods.oni2.net/node/4 Arena of Pain]
|30
|-
|2024/05/20
|[https://gamebanana.com/mods/514707 Kitsune: Chapter 1]
|20
|}

===Forum tutorials on level creation===
* '''[https://web.archive.org/web/20201029114347/http://oni.bungie.org/forum/viewtopic.php?id=2087 "Creating the Lair - A level tutorial"]'''
* [https://web.archive.org/web/20201127172559/http://oni.bungie.org/forum/viewtopic.php?pid=53026 "Creating a Custom Oni Level (s10k video tutorials)"]
* [https://web.archive.org/web/20201127180431/http://oni.bungie.org/forum/viewtopic.php?id=1515 "Creating new levels"]
* [https://web.archive.org/web/20201029114358/http://oni.bungie.org/forum/viewtopic.php?pid=33838 "Create levels with pathfinding grids"]
* [https://web.archive.org/web/20210117145338/http://oni.bungie.org/forum/viewtopic.php?id=2000 "More questions about levels"]
* [https://web.archive.org/web/20201029103906/http://oni.bungie.org/forum/viewtopic.php?pid=37252#p37252 "Modding Existing levels - Beta" ("Moveable furniture" post)]

===Wiki pages on level creation===
* [[Creating a level]] (you are here)
* [[Modifying an existing level]]
* [[New levels]]
* [[Lightmapping levels]]

===Free asset sources===
* [http://vk.com/gameready Various game meshes]
* [http://web.archive.org/web/20230601050258/http://tutorialsforblender3d.com/Textures/Textures_index.html Various game textures]
* [https://www.textures.com Various game textures]

==Engine limitations==
First you should be aware of the limitations that Oni will place on your level.

* The triangle limit of a game level is approx. 520,000 (consider it 500,000 to be on the safe side).
* {{ModTool}} can save DAE files with a maximum of 64,000 triangles per object.
* When polygons are too tightly packed, the camera will look at too many of them and glitches will appear. The limit on visible GQs (Gunk Quads) is 8,192 (213), and higher numbers will cause render bugs and produce the console error message "Exceeded max visible GQs ''number''". There are limited solutions to this:
** Decrease the '''gs_farclipplane_set''' value.
** Hide objects via '''[[#.3CModel.3E|env_show]]'''.
** Hide objects by ''level design''. For example, departments in a building could be quite detailed because the view of the other departments/rooms is blocked by walls.
* The camera can look at 2,049 transparent textures at once; one more, and Oni crashes.
* Characters are visible ''only'' within world coordinates {-4,099, -4,099, -4,099} to {4,099, 4,099, 4,099}.
* Geometry stops outside of (roughly) world coordinates -4,228 to 4,228 on the X and Z axes (vertical axis not tested).
* '''chr_debug_spheres = 1''' visualizes the collision spheres of characters, so you can check if they will fit through an entrance.

==3D tools==
===Problems when using multiple different tools===
Re-saving a DAE file in '''Mod Tool''' which was originally made in '''SketchUp''' can result in a surprising change in size within Oni. This is due to a difference in the specification of a scale unit.

: For example, the SketchUp DAE file may have: <tt><unit meter="0.0254000" name="inch" /></tt>
: And the re-saved Mod Tool DAE file may have: <tt><unit meter="0.1" name="decimetre"></unit></tt>

In that case you'll need to open the new DAE in a text editor and change the length specification back.

===Sketchup===
If you are working with Sketchup check out this pages:
* [http://oni.bungie.org/forum/viewtopic.php?id=2003 "Sketchup tutorials for making levels"]
* [[SketchUp tutorials and tips]]

===Blender===
'''Scaling'''

Same as Mod Tool and SketchUp: Caution with scaling: See [[#Problems when using multiple different tools|here]]

'''Pathfinding'''

Be sure to uncheck automatic triangle creation when exporting (BNV) geometry used for pathfinding. Ghost (''doors'') must be quads.

==Setting up a workflow==
If not noted differentely you need OniSplit v0.9.82.0 or a newer version. Onisplit can be downloaded [http://mods.oni2.net/node/38 HERE] (it also comes with the [[AE]] and is found in the Tools directory of the installation).

The level import demo files can be downloaded [http://mods.oni2.net/node/299 HERE].

First, put '''OniSplit.exe''' into the second '''lab''' folder alongside the XML files.

Look at the file '''build.cmd'''. These are the two important lines:

OniSplit.exe -create:level out lab.xml
OniSplit.exe -import:pc out level3_Final.dat

The first line creates the *.oni files from a master.xml file, in this case '''lab.xml'''. Once finalized, the resulting .oni files can be put into a new [[Making a mod package|AE package]].

The second line creates level archives which can be used for fast tests. They don't require you to install a package through the AE Installer.

Instead of "-nosep" you can now also use "-pc" for the import. Macs, however, do use "-sep".

==Troubleshooting==
If the game crashes while loading at ~90% progress, be sure that the texture's x and y dimensions are powers of two: 64, 128, 256, 512….

If the game crashes while loading at ~50-60% progress, be sure that the BINACJBOCharacters or AISA file has a player character defined.

If the game crashes while loading ~5-10% progress, check if all your textures were inside the "out" folder.

:You can extract the AKEV file to XML, then search for the [[XML:AKEV#TXMA|TXMP Array]].

:[http://mods.oni2.net/system/files/AKEV_texture_checker.txt THIS] script checks which textures are missing by comparing the AKEV*.xml with its *.oni files folder. Change the two paths so that it works for you: Alt+4, insert code, then F5.

"TXMP_marker_door" and "TXMP_marker_ghost" will be missing in the demo's "out" folder.

You can add this between the other two lines in build.cmd to prevent a crash.
OniSplit.exe -create:txmp out env/markers/*.tga

==Terminology==
;Polygon
:A polygon is a shape defined by points (vertices) in space. Polygons are the most fundamental building block in games. Oni uses only shapes with 3 and 4 points (triangles and quads). Other games might also use N-gons, shapes with more points.
;Face
:The '''surface of a polygon''' is also named face. The '''direction''' of a face in '''defined by its normal'''. If an object seems to have a hole, it might be that the polygon just has a '''flipped normal''' and is therefore wrongly rendered (displayed on screen).
;Normal
:Faces and even vertices themselves have directions. The normals of vertices determine how smooth or sharp edges will appear.
;Vertex (plural<nowiki>:</nowiki> vertices)
:A point within a polygon.
:Vertex colors radiate from one vertex to another vertex, whereby their different color values blend into each other so that gradients can appear.
;Edge
:A line of two points within a polygon.
;Tris (triangles)
:Polygons made of 3 points.
;Quads
:Polygons made of 4 points. Planes. Rectangles.
:Internally, all quads get converted into two triangles and will affect the maximum triangle count accordingly.
;Level
:The term "level" is often used to shorten "level map" (buildings and terrain).
;Geometry
:Level geometry can be objects made of tris and/or quads.
:Oni differentiates between basically 3 types of level geometry:
:* Static objects (sometimes also named AKEV core geometry)
:* Animated objects
:* Pushable objects (not used in the original game)
;Static geometry
:* '''Unique level geometry with no functions''' (AKEV core geometry such as buildings and streets).
:* '''Repeating objects''' are flagged as '''furniture (FURN)''' although they can be outdoor objects such as boxes and containers. FURN objects were used to be imported by an object collection, an CJBO. Nowadays, furniture collections can be used (again) for imports, but the individual objects are stored as OFGA files. This modularity is known in many game editors (like the Unreal Engine Editor). So, '''OFGA are nothing else than "game assets".''' The drawback of OFGA is that they '''will not import with any vertex shading'''. Only their '''geometries''', attached '''particle''' and '''gunk flags''' get copied into final (baked) level geometry.
:* '''Objects with actual functions''' (CJBO such as doors, consoles, triggers)
:** Some types of CJBO (spawn lists of weapons, characters, powerups and of course flags and patrol paths) are not considered as level geometry.
;[[XML:AKEV#AGQG|Gunk flags]]
:Properties directly associated with the polygons. Among others, these can be: Transparent, TwoSided, NoCollision, Invisible, NoObjectCollision, NoCharacterCollision, NoDecals, Furniture, Impassable.
;Baking
:When a level gets baked, all geometries get merged.
:*Unique level geometry will have vertex painting.
:*Objects derived from already compiled oni-files (shared classes) will have no vertex painting.
:*Animated and pushable objects will have no vertex shading.
;Vertex shading
:Vertex colors (vector data) can be painted onto core geometry.
:They are used as a rudimentary form of lightmapping (pixel data).
:Having vertex shading is still better than having no vertex shading at all. It makes the level appear more lifelike.
;Lightmapping
:In other games, lights and shadows are added to level geometry with lightmapping.
:There were experiments to bring lightmaps back to Oni. The technique come with a major drawback though. It doubles the triangle count and adds many textures.
;In-game
:When you are "inside" the game, running or playing it.

==Level construction==
'''Visible environment'''
* A '''level map''' consists of visible geometry: terrain and buildings. This is also named the '''environment''' or for short '''env'''.
** Use '''quads''' of approximately 10 up to 20 meters in size to construct env geometry.
* Anything other than floors and simple walls will be made of triangles.
** Geometry from CJBO works best with triangles. Quads might show holes in-game.
'''Invisible pathfinding'''
* '''AIs''' (or non-player characters, NPCs) need '''pathfinding''' data, usually shortened as '''bnv'''.
** Pathfinding data can be described as geometry, therefore as rooms. These '''bnv rooms''' are made of '''floors''' and are connected by '''ghost''' quads which work like doors. AIs can move from one room to another room only by passing a ghost. Therefore, ghosts have the same width as rooms in open terrain.
*** Use floor quads of approximately 10 meters in size to construct BNV floors.
*** Put ghost quads exactly on the edges of BNV floors with an angle of 90 degree.
'''Support for [[XML:BINA/ONIE|effects]]'''
* Effects such as decals that indicate damaged environment need level textures to be registered in [[XML:BINA/TMBD|TMBD]]. Make sure not to replace existing texture entries but to add your own so that the other levels remain unaffected.
'''Level logic'''

BSL scripts bring levels fully to life. The logic is mostly event driven whereby different checkpoints and conditions must be reached.
* Checkpoints are actually [[XML:BINA/OBJC/TRGV|trigger volumes]] that can recognize entering and exiting characters.
* The second most important source of events are [[XML:BINA/OBJC/CHAR|character (script) functions]], especially the die function of enemies.
** To support good and less good players alike, NPC characters can feature the UpgradeDifficulty flag. Also, BSL scripts can detect the current [[BSL:Game_status|difficulty level]].
* [[XML:BINA/OBJC/TRIG|Laser triggers]] are mostly used to control [[XML:BINA/OBJC/TURR|turrets]]. [[XML:BINA/OBJC/CONS|Consoles]], triggers and [[XML:DOOR|door]] unlocking are used to set up very simple "riddles”.
* The creation of cut scenes is time-consuming quality work. Due to missing tools for streamlined workflows, it is totally okay for you to skip this.
** New synchronized FILM, OBAN and TRAM files are required for cut scenes. Not to mention sound files for dialog.

==The master XML file==
''The project file for level creation.''

The '''master XML''' file's '''name determines''' the '''BSL folder name''' and the '''AKEV and ONLV file names''' in the output folder. File paths in the XML can be either absolute or relative.

'''Mandatory files''' for level import:
* ''level_environment''.dae
* ''level_bnv''.dae
* ''level_textures.tga/jpg/png''
* Character.xml or AISA with player
* ONSK name in <Sky> (in Windows, this can be a fake name; does the Mac need actual ONSK files?)
* ONLD file for the new level; read [[Making_a_mod_package#Mod_Info.cfg|HERE]] about making sure your level is unlocked (accessible on the Load Game screen)

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
|valign="top"| <Level SharedPath="...">
|valign="top"| link
| The master XML file can link to other XML files. Most of them will be [[OBD:BINA/OBJC#OBJC_types|BINACJBO]] files. The file type is declared inside the file, so the file name itself doesn't have to contain the type. Ergo, "BINACJBOCharacter.xml" can be given a simpler name like "Character.xml".

Some resources used by those XML files can be found in a '''shared''' folder. OniSplit copies textures and "physics" objects into the output folder; furniture objects will be integrated into the AKEV. Unused resources in the shared folder will be ignored. That way the final level archive or AE package contains only the necessary files, saving disk space for the end user.

In the demo are various subfolders in the '''shared''' folder: consoles, doors, furniture, triggers and turrets. These file types do not need their file prefixes: CONS, DOOR, TRIG and OFGA. OniSplit will recognize them nonetheless.

'''Common mistake:'''

CJBO files '''need relative paths to the resource instead of just file names'''. Taking consoles, for example: a standard export to XML gives you "console_data". But to use the shared resources these must be paths like "'''consoles/console_data.oni'''" as they are stored in '''shared/console/'''. Note how the demoed '''shared''' folder is placed next to the [http://mods.oni2.net/node/299 project ("lab")] folder and the XML master file points to it using "../shared".
|-
| <Environment>
| -
|
|-
| <Model>
| -
| Used to import level geometry and static objects. See [[#<Model>|HERE]] for detailed information.
|-
| <Import Path="..."/>
| link
|
|-
| <Node Id="...">
| string
| informational (space for notes)
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Can be used with BSL commands such as ...
: [[#<Model>|env_show ID 1]] (use 0 to hide)
: [[#Breakable glass with BSL recognition|env_broken ID1 [ID2]]] (if a second ID is supplied then objects in the range ID1..ID2 get counted; "3001 3018" would cover 18 objects)
: [[#Texture exchange|env_texswap ID texture]] (no file prefix/suffix allowed)
: [[#env_shade|env_shade ID ID R G B]]
Static objects store their ID in [[XML:AKEV#IDXA_.28quad_group_id.29|one of AKEV's IDXA instances]].
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
|valign="top"| <Rooms>
|valign="top"| -
| For detailed information see [[#<Rooms>|HERE]].

For a Google SketchUp BNV tutorial see [http://oni.bungie.org/forum/viewtopic.php?pid=36760#p36760 HERE].
|-
| <Import Path="..."/>
| link
| File path to *.dae file. BNV data, used to create pathfinding.
|-
| <Textures> {{Anchor|textures_tag}}
| -
| With OniSplit v0.9.94.0+ you can use attributes to set the default import formats and max dimensions. For example:

: <Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">

Textures with a dimension that isn't a power of two (2x) and textures larger than 512px on a side will be resized. For example, 2003x2000 will become 512x512. (What would 257x255 become?)
|-
| <Texture Name="...">
| string
| TXMP file name to generate.
|-
| <Flags>
| flag
| Optional tag. For list of flags see [[XML:TXMP|HERE]].
|-
|valign="top"| <Format>
|valign="top"| flag
|
:DXT1
:BGR
:RGBA
:BGR555
:BGRA5551
:BGRA4444
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
| <Image>
| link
| File path to *.tga/jpg file.
|-
|valign="top"| <Sky>
|valign="top"| string
| ONSKfile.oni (without file pre- and suffix)

The import doesn't work with an empty tag. <Sky>clear</Sky> helps here; any other fictional name will also do.

For detailed information see [[XML:ONSK|HERE]].
|-
| <Objects>
| -
|
|-
|valign="top"| <Import>
|valign="top"| link
| File path to an OBJC (collection) file. Supported collection files for <Import> are:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[#Furniture.xml|Furniture.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[#Physics.xml|Physics.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

The following two collection files are '''NOT''' supported. You need to copy them as regular pre-compiled *.oni files into your mod package:
: [[XML:BINA/OBJC/MELE|Melee.xml]] (overrides global MELE; not used in vanilla levels)
: [[XML:BINA/OBJC/CMBT|Combat.xml]] (overrides global CMBT?; not used in vanilla levels)

'''Inside''' the following three supported collection files, provide links to pre-compiled (*.oni) class files: console, door and furniture collections. Use relative paths such as:
:: <code>'''consoles/'''console_data'''.oni'''</code>
:: <code>'''doors/'''TCdouble'''.oni'''</code>
:: <code>'''furniture/'''V_tctf_bigvan'''.oni'''</code>

When you are unsure about the folder structure refer back to the [http://mods.oni2.net/node/299 level import demo].
|-
| <Films>
| -
|
|-
| <Import>
| link
| File path to *.xml file. OniSplit creates a [[XML:FILM|FILM]] file from it. Used for characters in cutscenes.
|-
| <Cameras>
| -
|
|-
| <Camera Path="...">
| link
| File path to *.dae file. OniSplit creates an OBAN file from it. Used for cutscenes.
|-
| <Animation Name="..."/>
| string
| Name for the OBAN file.
|}

This is a trimmed-down version of the master file '''lab.xml''' from the demo. It's meant to give you a first impression. We might upload a smaller demo someday with all features nonetheless.

<?xml version="1.0" encoding="utf-8" ?>
<Oni>
<Level SharedPath="../shared">
<Environment>
<Model>
<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_bomber_window.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>
</Model>
<Rooms>
<Import Path="env/lab_bnv.dae"/>
</Rooms>
<Textures>
<Texture Name="GOO">
<Format>bgra4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>
</Environment>
<Sky>sunset</Sky>
<Objects>
<Import>Character.xml</Import>
<Import>Furniture.xml</Import>
<Import>TriggerVolume.xml</Import>
<Import>Physics.xml</Import>
</Objects>
<Films>
<Import>films/BomberKonRun01.xml</Import>
<Import>films/BomberKonRun02.xml</Import>
</Films>
<Cameras>
<Camera Path="cameras/BomberCam01.dae">
<Animation Name="BomberCam01"/>
</Camera>
<Camera Path="cameras/BomberCam02.dae">
<Animation Name="BomberCam02"/>
</Camera>
</Cameras>
</Level>
</Oni>

===<Model>===
This tag is mandatory (it must be present to avoid errors); the model section contains one import path to the AKEV (level) geometry (*.dae) and can contain additional import paths for exceptions (*.dae).

Data from the demo:

<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>

'''env_show'''

The motorcycle has here scripting ID 9. You can show and hide the object with the BSL command '''env_show''', where the second parameter means true or false. '''Never use 0 as an ID''' because it won't work.

env_show 9 1
env_show 9 0

EdT demonstrates env_show [https://www.youtube.com/watch?v=Em6wa5JTQNM here]. Note how the objects have collision.

The last vanilla level (Syndicate Mountain Compound) has a big satellite dish platform that can be made hidden. Obviously, such objects/areas can be made to have pathfinding too.

;More possible applications of env_show:
* ground/ceiling/objects for cutscenes that become partially destroyed
* destructible walls like in Deus Ex: Human Revolution (trigger volume, replacing punch anim with punch-through-wall anim)
* grids in front of ventilation shafts (a small door object could be an alternative)
** at the moment this can't be done because characters can't sneak under the top edge of the opening (the characters collision spheres are too big)
* managing object groups with trigger volumes (save multiple objects in one DAE file)



====Import of object groups====
'''Mod Tool versus SketchUp'''

The meaning and behavior of "groups" greatly differs in these two programs.

:'''In SketchUp''' you can group objects which enables you to easily duplicate all objects inside a group and to scale/rotate/translate them all together.

:'''In Mod Tool''' grouped objects are still loose, and duplicating a group won't duplicate the objects. To achieve the same effect as in SketchUp, you have to create a hierarchy where any one object is the "parent" and all others the "children".

'''Google SketchUp'''

To create a group, select two or more objects, right-click on the selection and choose "make group".

[[Image:ModTool_can_import_objs_in_hierarchies.jpg|right|thumb|Mod Tool can import objects in hierarchies to Oni.]]
'''Mod Tool'''

Either use the Explorer (A) or the Schematics (B) to create a hierarchy.

:(A) In the Explorer window, drag and drop one or more objects onto another one.

:(B) Open the constrain tab at the right side. Select parent object, click "Parent", click the child object(s). Check the result in the Schematics window.

:'''Mod Tool: caution when saving to DAE!'''

:A normal selection won't do. You have to select the object tree to successfully save a hierarchy. This is the same way that you do it with Oni characters.


====Breakable glass with BSL recognition====
Broken environmental objects can be recognized by the BSL command ''env_broken (ID_1, ID_N)''. However, this requires additional code to work.

An example is the training level. Let's determine how we can set up such a thing.

First we need a [[XML:BINA/OBJC/TRGV|trigger volume]] like in level 1.

<TRGV Id="11495">
<Header>
<Flags>Locked</Flags>
<Position>-714.6615 -298 -555.2073</Position>
<Rotation>0 0 0</Rotation>
</Header>
<OSD>
<Name>tv75</Name>
<Scripts>
<Entry></Entry>
<Inside>targets_gone</Inside>
<Exit></Exit>
</Scripts>
<Teams>255</Teams>
<Size>400 31 270</Size>
<TriggerVolumeId>75</TriggerVolumeId>
<ParentId>0</ParentId>
<Notes></Notes>
<Flags>PlayerOnly</Flags>
</OSD>
</TRGV>

Now we need some BSL code.

var int inside_target_function;

func void enter_target_function(void)
{
dprint enter_target_function
inside_target_function = 1;
}

func void exit_target_function(void)
{
dprint exit_target_function
inside_target_function = 0;
}

func void targets_are_not_gone(void)
{
# CB: turn off the trigger volume and sleep for a second
# so as not to cause hideous performance loss
trigvolume_enable tv75 0
sleep 60
trigvolume_enable tv75 1
}

func void targets_gone(string ai_name)
{
if (inside_target_function eq 0)
{
enter_target_function() # catch other "targets_gone" functions to let them do nothing

var int num_broken = env_broken(3001, 3018);
# if you only one target use scheme: env_broke(3001, 3001)

if (num_broken eq 18)
{
targets_are_gone();
}

if (num_broken < 18)
{
targets_are_not_gone(); # to set check interval to one second
}

exit_target_function
}
}

func targets_are_gone
{
trigvolume_enable tv75 0
# [...]
}

;Explanation:

Player enters the TV, targets_gone() gets triggered. The variable "inside_target_function" should be 0 by default, so we will enter the "if" block. Next, we can assume that the player didn't destroy all glass objects, so "num_broken" will be less than 18; thus, targets_are_not_gone() gets called.

The TV function targets_gone() ''would'' be triggered every frame, but targets_are_not_gone() creates a delay between checks: the TV gets deactivated for 60 frames. Then the TV becomes enabled again and will start anew until all glass objects got destroyed or player left the TV.

In this case the targets_gone() function will do nothing because "inside_target_function" was set to 1 by the first call.

targets_are_gone() eventually disables the TV to prevent memory overflow; this function also contains all the things ("[...]") that you want to happen after the glass target is broken.

====Texture exchange====
BSL command supported on Windows and Mac:
: env_texswap ID texture

Might be useful to switch on/off static and animated textures. (News broadcast screen: running or off or smashed. Lava stream: flowing or stagnating or cooled down. Etc.)

A similar effect can be achieved by showing/hiding geometries with different textures as EdT has demonstrated in a private test. That way it should also be possible to have different vertex coloring for an area.

====Vertex coloring====
Vertex colors can be edited manually in Blender by setting up following 3 things:
* Properties Panel > Data > Color Attributes
* 3D viewport (left top) > change work mode to Vertex Paint
* 3D viewport (right top) > change to Viewport Shading to Solid mode (under the dropdown menu you can choose "flat" to have full saturation)

{{divhide|Mod Tool}}

[http://web.archive.org/web/20170529111607/http://softimage.wiki.softimage.com/xsidocs/tex_vcolor_CreatingColoratVerticesCAVMaps.htm SoftImage documentation.] Observation: The sniper tower from level 19 Syndicate Mountain Compound can be isolated and re-imported as it is. It will appear quite dark.

If we remove "_color" from the object, the shadows will be gone next time we import the tower.

Mod Tool: Explorer [8]

Object
|
+-- Polygon Mesh
|
+-- Cluster
|
+-- Polygon
| |
| +-- [...]
|
+-- NodeProperties
|
+-- '''_color'''
+-- texcoord (Explicit UVWs)
|
+-- Vertex_Color_Def

So, how do we modify that data?

'''Single object shading'''

If there's already a vertex color property, you can use Shift + W to activate the Paint Vertex Color Tool. With Control + W you can change the brush color. R + Hold Click + Move Mouse let you change the brush size. The more vertices (points) you have, the more detailed you can make the shadows/colors. But keep in mind that too many polygons can destroy collision, making characters fall through the ground.

If there's no vertex color property, the first usage of Shift + W will create that property. But you can also manually create it via Property > Color under Vertices Map.

'''Level-wide shading'''

[[Image:light_test_modtool.png|right|thumb]]
[[Image:light_test_ingame.png|right|thumb]]

To get general shading/lighting you can set up light sources. "Infinite" lights are useful for global lighting, while "Light Box", "Point", "Neon" and "Spot" are more suitable as local light sources. They can be accessed via Primitives > Light.

By default, a Mod Tool scene has one Infinite light, but it doesn't shine in every direction so you might want to add more Infinite lights. Let's say one Infinite light for each direction (+X, -X, +Y, -Y, +Z, -Z) with an intensity of circa 0.25 (night) or 0.75 (day).

The illumination of those lights can be integrated into the vertex color property. There's some information [http://oni.bungie.org/forum/viewtopic.php?pid=29089#p29089 on OCF here]; the quoted information is in triplicate, so don't get confused by that: at first it's detailed, then summarized, then as a checklist.

Basically, you can go with the checklist:

* Property > Color At Vertices Map
* Property > Render Map
* In render map property page, under Sampling select Vertices Only
* Under Surface Color, choose Enable, then in the box below select Vertex _Color; if that option does not appear, click on the New button next to it
* Under Map, select Illumination only
* Finally, click on the button Regenerate Maps...

This must be done for all objects separately.

: [http://mods.oni2.net/system/files/vertex_color_script.txt There's a script here] which can apply vertex color and render maps to all '''selected''' objects. Load it into the script editor with Alt + 4 and hit F5 to run it. (Be sure the script's language was set to VBScript.)
: The variable "overwrite_VC" can be changed.
:: With "1" all existing CAV maps of selected objects will be overwritten. This can take some time.
:: With "0" only selected objects without CAV maps will be the script's target.

'''Notes on ModTool view modes'''
* "Constant" let you see the colors of the vertex coloring only.
* "Textured Decal" let you see object textures only.
* "Shaded" let you see the illumination only.
* "Textured" let you see the textured object with illumination and vertex coloring.
{{divhide|end}}

=====env_shade=====
If you use '''env_shade''', use it with caution. It completely overwrites the vertex coloring.

# BSL command
# env_shade obj_id obj_id R G B

# examples
env_shade 7 7 # object 7 will be black
env_shade 7 7 0 0 0 # object 7 will be black
env_shade 7 7 .31 .999 .5 # object 7 will be quite green
env_shade 7 10 1 1 1 # object 7, 8, 9, 10 lose all their shading

====Baked lightmaps====
A drawback of this method, AKA shadow maps, is the high number of [[XML:BINA/TMBD|TMBD]] changes and new textures for every wall, requiring a lot of memory. How to create shadow maps:

* https://web.archive.org/web/20121105081823/http://www.game-artist.net/forums/support-tech-discussion/5622-burning-shadows-onto-texture-xsi.html


Notes on map options:
* "Surface color and illumination": outputs used texture with added shadows
** Can be used to replace original texture
* "Illumination only": output a texture that only contains the shadows
** Can be used on a new overlying, transparent surface

====Standalone lightmaps====
With this approach there are two meshes, whereby the shadow effects on one mesh get drawn in front of the regular level texture.

Compared to the "baked lightmaps" method, this needs more polygons of course. And these polygons are transparent, which is a problem with Oni's limited rendering ability for such textures. However, standalone lightmaps only need a few new textures if used wisely.

Read [[Lightmapping levels]] to learn more.

[[Image:Oni_Lightmaps_double_polygon_method.jpg|center]]

===<Rooms>===
The Rooms tag is mandatory. It contains an import path to BNV and ghosts (*.dae) which are used to create pathfinding grids. For information on the binary data behind this, see [[OBD:AKVA|HERE]].

Sample code from the master XML file:
<Import Path="env/lab_bnv.dae"/>

'''Fundamentals'''
* '''BNVs''' are '''volumes''' (sometimes also named '''rooms''') that have a pathfinding grid assigned to them.
* For practical reasons you only need '''floors and ramps''' to build a BNV. (As seen [http://edt.oni2.net/images/Hideout_BNV.jpg HERE.])
** A BNV polygon can consist of 3 or more points, but it's recommended to use '''shapes with 4 points''' because the other shapes usually waste more grid space. At the moment you can import only '''[[wikt:convex|convex]]''' shapes.
* Secondly, there are so called '''ghosts''' (vertical quads) that connect '''neighboring BNVs'''. AI can only transit from BNV to another through ghosts.
: OniSplit gives error messages for ghosts that don't have 2 neighboring BNVs, for example:
BNV Builder: Ghost 'grid2' has no adjacencies at <-72,41 1,999 -166,6> and <-71 1,999 -168,21>, ignoring

'''Tolerance values'''
* Horizontal distance from room to ghost: 1
* Vertical distance from room to ghost: 18
* Ghost's horizontal dimension must be greater than 0
* Under optimal circumstances, pathfinding works on a plane that is +4 world units above or -0.5 below the pathfinding grid
* Normally characters can't pass over low vertical walls such as stairs/curbs if those don't have a ramp under them; near ground level (Y=0) is an exception where characters are allowed to step on a plane that is 4 world units above pathfinding grid; higher planes need a ramp
* Maximum angle of ramp you can go on is 70°; higher angles will make characters fall through to their death (in those cases you might want to add invisible walls/boxes to prevent them from touching the ramp)

'''More notes on PF processing'''
* Actually, BNV and ghosts can have any name and don't need any texture.
* During pathfinding calculation, OniSplit creates a new folder called "temp" and a subfolder "grids". There is a file named "''levelname''_grids.dae". That file contains rooms with textures called "bnv_grid_''N''.tga" which mark obstacles in the pathfinding grid. Ghosts will have a transparent texture "'''_marker_ghost'''.tga". You also get these when you export a level. Transparent ghosts make it easier to see the rest of your level if you have many of those planes.
* In Mod Tool, ghosts and rooms can be grouped under a null object. Right-click the null object to select all its children, then use "Selection Only [x]" as your saving option. That way all the planes can be quickly saved to a *.dae file.
* You can influence the pathfinding creation of dangerous zones using danger quads. Read about those [[#Marker textures|HERE]].
* Another kind of influence is the [[#<Model>|gunk flag]] IgnoreGrid. It can be used to tell OniSplit to ignore the object during pathfinding creation. The grids in that place will be white.

[[Image:Pathfinding_grid.jpg|thumb|200px|right|'''ai2_showgrids = 1''' in action]]
'''BSL commands'''
* chr_show_bnv = 1
:: shows number of BNVs the player is standing on
* ai2_showgrids = 1
:: shows pathfinding grids
* ai2_chump
:: spawns a friendly Striker that follows the player if possible, makes also pathfinding grids visible
* ai2_chump_stop = 1
:: Striker stops following you
* ai2_chump_stop = 0
:: Striker follows you again

====Pathfinding on uneven ground====
Pathfinding works on slightly uneven ground as long as the polygons are 0.5 world units beneath or 4 world units above the BNV.

For greater surface irregularities, we can use a trick:
* The problematic polygons must be saved to a DAE file and then referenced in the model section as an individual object.
* Then the <GunkFlags> tag needs to be '''''GridIgnore'''''.
* Additionally we create a plane (invisible if necessary) under the object so that Oni doesn't think there's a hole.
* The ghosts must be taller than the highest polygon to be walked on. (This has been tested up to a height of 2,000 world units.)

'''Symptoms of too-small ghosts'''

A) AI can't run at all.

B) AI loses PF ability if the tracked enemy performs animations that are outside of the pathfinding volume. Here's a video (<nowiki>https://youtu.be/vfKPzP5hiCo</nowiki>, dead link) showing these symptoms.

'''Missing boundaries'''

Let's say you have a BNV, tall ghosts, and a GridIgnore-flagged hill with trees and bushes and stuff.

Why do AIs run up against the trees?
: '''Problem:''' There are no red/orange grids that limit the AI's movement. Normally, objects will produce red pathfinding squares around them. But objects that are 20 world units above the BNV are ignored just like objects with the IgnoreGrid flag.
: '''Solution:''' Add simple geometries like ''_marker_impassable fences'' or danger quads near the BNV.

'''Disappearing AIs'''

The ground is sometimes not solid, and the player and AIs are falling through it.

: '''Problem:''' On GridIgnore-flagged uneven ground, AIs can fall through it when they are out of the player's view.
: '''Solution:''' Use either '''chr_lock_active ''AI_name''''' or '''chr_all_active = 1'''

====Debugging====
'''(OniSplit v0.9.93.0+)'''
[[Image:OniBrowser.jpg|thumb|200px|right|OniBrowser displaying level geometry plus PF and ghosts.]]

* '''env_show_ghostgqs = 1''' makes the ghost quads visible
** The original ghost quads can't be seen; per Neo, "they are not included in the octtree and bsp tree"
** To see them you must use the -debug option in the level creation command (available with OniSplit '''v0.9.93.0+''')
OniSplit.exe -create:level ''output_folder'' '''-debug''' ''input_folder''/''master_xml_file''.xml

Not all debugging/testing needs to be done in Oni. There is also a [http://mods.oni2.net/node/256 program] (Windows only) which can display the whole level.

For example you can load an AKEV*.oni, select the level name, and use the hotkeys [B] and [P] to display BNVs and ghosts.

'''Bug prevention:'''

After all testing is done, you should compile the level a last time without the -debug option.

AIs appear to have trouble shooting through ghost quads that got registered in the octtree/BSP tree as seen here (<nowiki>https://www.youtube.com/watch?v=-ZugVBgBVKc</nowiki>, dead link).

====When OniSplit fails to connect PF quads====
[[Image:Pathfinding_creation__merge_polygons_to_fix_connections.jpg|thumb|200px|right|Fixed PF in compound level after underground construction...]]
It can help to merge polygons to one object and merge their edges. These become white. (Outer edges are blue.)

===<Textures>===
====...used for exceptions====
The [[#textures_tag|textures tag]] is mandatory.

AKEV textures will be imported by the master XML file automatically; you don't need to add them to that file.

: With OniSplit v0.9.82-93.0, the textures' formats will be DXT1 and (for transparent ones) BGRA4444.
: With OniSplit v0.9.94.0+ the textures' formats will be BGR and (for transparent ones) RGBA.

To change the default texture import format, use the Texture'''s''' tag. (Possible with OniSplit v0.9.94.0+.)

To change the format/flag/gunk flag of a specific texture, use the Texture tag.

An example:

<Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">
<Texture Name="GOO">
<Flags>TwoSided</Flags>
<Format>BGRA4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>

* Use the gunk flag "TwoSided" to make surfaces visible from both sides.
* If the texture comes with the gunk flag "NoCollision" then all objects with that texture will have no collision. Characters would fall through it.

Transparency and no collision together would make sense for a water-like substance. The Vago Biotech level uses this approach for the area with green toxic waste.

[[Image:making_a_surface_transparent_and_twosided.png|thumb|200px|right|'''Figure 1''']]

[[Image:AKEV_single_object_multiple_textures.png|thumb|200px|right|'''Figure 2''' one object with multiple textures, one per polygon cluster]]
[[Image:AKEV_single_object_multiple_textures_ingame.png|thumb|200px|right|'''Figure 3''' blue: two-sided glass: two-sided and transparent random metal: no flag (one-sided)]]

'''TwoSided and transparent objects'''

It's also possible to set this in Mod Tool. For TwoSided-ness, use one image source for diffuse and transparency. (It won't work with two image sources even if both sources use the same image.)

For transparency you must additionally use the three checkboxes:
* Transparency: Enable
* Transparency: Use Alpha
* Transparency: Invert

See '''Figure 1'''.

====Regular textures====
OniSplit automatically imports textures of objects in the [[#<Model>|<Model> section]]. Those objects could be considered as AKEV core geometry.

'''One texture per object'''

Furniture and Physics objects are allowed to have only one texture per object. AKEV core geometry can have one texture or multiple textures – that's up to you to decide.

'''Multiple textures per object'''

'''Question:''' How do we apply multiple textures to an AKEV core object?

'''Answer:''' Assuming you are using Mod Tool the procedure will be as follows. Repeat this for each cluster you create (except for projection). See also '''Figure 2 and 3'''.

* Select some polygons
* Go to Material > Phong
* Hit [7] to open Render Tree
* Add a texture and connect "Image" with "Phong", choose "diffuse" as illumination mode
* Double-click "Image" to open Material page
* In the Texture Projection section, click on "New" and choose a suitable projection
** Do this only if there isn't a projection in the "Texture_Coordinates_AUTO" cluster yet
** OniSplit processes only one texture projection, see '''Figure 4'''
* Choose the texture and UV, then fine-tune the UV via Alt + 7

[[Image:AKEV_multiple_textures_one_projection.png|thumb|200px|right|'''Figure 4''' use only one texture projection per object]]

Caution: textures will be fixed to one set of flags. You can't use the same texture A for a one-sided cluster/object B and a two-sided cluster/object C. You would need to create a differently-named clone of that texture and apply that to cluster/object C.

====Marker textures====
Marker textures are used to import certain objects with special flags. Import those objects alongside [[#<Model>|AKEV core]] geometry.

Marker textures aren't imported automatically. Add those textures to the final package or plugin yourself, e.g. with some sort of script.

OniSplit.exe -create:txmp out env/markers/*.tga

The flags Transparent, TwoSided and NoOcclusion are only set if the same texture source is used for diffuse and transparency and if transparency setting are enabled. See the subsection under "[[#...used for exceptions|...used for exceptions]]" called "TwoSided and transparent objects".

'''Danger quads'''

Pathfinding grids have different colored squares with different meanings.
* white/gray - clear space
* green light - near wall
* green - semi-passable
* green dark - stairs
* blue very light - border 1
* blue light - border 2
* blue - border 3
* blue dark - border 4
* '''orange - danger'''
* red - impassable

For detailed information on colors, see [[OBD_talk:AKVA/0x24#EFFECTS_of_various_pathfinding_grid_tile_types|HERE]].

Normally, OniSplit decide how to color the grids. But it's possible to add your own danger quads to fine-tune zones of higher danger. Those orange areas will be generated with the 4 different blue borders around it.

Danger quads must have "'''_marker_danger'''" as texture name.

Results in flags: Transparent TwoSided NoCollision Invisible NoOcclusion Danger

'''_marker_barrier'''


Results in flags: Transparent TwoSided(double-check) Invisible NoObjectCollision NoOcclusion

'''COLLISION (boxes)'''

AIs can get stuck in detailed geometry. This can be prevented with collision boxes. In-game the box will be invisible, but has collision so characters can't get through. The pathfinding grid will be red where it comes in contact with the box; the red is followed by a light green and then regular green.

[[XML:OFGA|OFGAs]] use the COLLISION texture. Onisplit doesn't automatically apply gunk flags to it. You need to use XML tags for that. Typically it would be <GunkFlags>Invisible NoObjectCollision</GunkFlags>

'''Stairs'''

Texture: '''_marker_stairs'''

Normally, characters can't move on stairs because they contain vertical rises. In this case you can use a sloping quad that is above or inside the staircases. It's possible to set the desired flags in the <Model> section, but doing so and exporting these self-made stair ramps is wasted time. Simply apply _marker_stairs to that quad and characters will be able to move on that surface.

Resulting flags: Stairs Transparent TwoSided Invisible NoObjectCollision NoOcclusion

This has no effect on pathfinding creation. Regularly-textured stair geometry (which intersects the marker quad) will be flagged as NoCharacterCollision.

'''Impassable'''

texture: '''_marker_impassable'''

Resulting flags: Transparent TwoSided (<-double-check this) Invisible NoOcclusion

Impassable walls are very similar to collision boxes except that particles can also collide with them. The pathfinding grids will be also red, light green, and green.

'''Blackness a.k.a. jello fix'''

Texture: '''_marker_blackness'''

Resulting flags: TwoSided NoCollision

Simply black walls. No effect on pathfinding creation. The purpose of these walls in Oni is to block out areas outside of a level's outermost wall so that the Jello-cam cannot show the player other parts of the level when it escapes a wall. See [[Jello-cam]] for details.

'''Doors'''

Texture: '''_marker_door'''

Resulting flags: DoorFrame Transparent TwoSided NoCollision NoOcclusion

Don't use this.

===<Objects>===
Information on regular object lists can be looked up here:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

====Furniture.xml====
The AKEV core geometry is more or less the overall structure of the level while this furniture file adds standard objects (e.g. crates and desks) to it.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Objects>
| -
| This tag marks the file as BINACJBO.
|-
| <Furniture>
| -
| This tag marks the file as FURN.
|-
| <Header>
|
|
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag. Ignore it. Those flags were used in the past.
:None
:Locked
:PlacedInGame
:Temporary
:Gunk
|-
| <Position>
| float x3
| Optional tag. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag. X Y Z rotation.
|-
| <OSD>
| -
|
|-
|valign="top"| <Class>
|valign="top"| link
| File path to a '''pre-compiled [[XML:OFGA|OFGA]] (*.oni) file'''. Use it as part of a relative path. Make sure that the OFGA comes with the files it needs: M3GM and TXMP.

An OFGA can hold multiple M3GMs. That 3D content will then be integrated into the AKEV.
|-
|valign="top"| <Particle>
|valign="top"| string
| This name gets written into <Tag> inside ONLV (ENVP section) and can be used with BSL commands, e.g. you can take control over a particle via '''particle BSL_name start'''. For more commands, see [[XML:BINA/OBJC/PART#BSL_support|HERE]].

Take care with the naming of new OFGA files. The particle name will be composed of 2 parts separated by an "_" underscore. When one tag is empty, the final name will contain an underscore nonetheless. '''Examples:'''

: FURN <Particle>test</Particle> + OFGA <Tag>streetlight</Tag> = '''test_streetlight'''
: FURN <Particle></Particle> + OFGA <Tag>streetlight</Tag> = '''_streetlight'''
: FURN <Particle>test</Particle> + OFGA <Tag></Tag> = '''test_'''
|}

;Example

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Objects>
[...]
<Furniture>
<Header>
<Flags>Gunk</Flags>
<Position>-62.692 -29 108.35</Position>
<Rotation>181.522 356.021 178.114</Rotation>
</Header>
<OSD>
<Class>furniture/V_tctf_bigvan.oni</Class>
<Particle></Particle>
</OSD>
</Furniture>
[...]
</Objects>
</Oni>

====Physics.xml====
This file is for objects with "physics". Unlike AKEV core geometry or furniture, these objects can be animated.

: A small video tutorial on [https://www.youtube.com/watch?v=CFNseg_2UxA how to create a simple animated object]

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Physics>
| -
|
|-
| <Object Name="...">
| string
| Use a unique name for each object.
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Tested with BSL command...
:obj_create ID [ID]
:obj_kill ID [ID]
:env_anim ID [ID]
:env_setanim ID [ID]
The scripting ID will be stored in the ONLV's OBOA instance.
|-
|valign="top"| <Flags>
|valign="top"| flag
|
;Object setup flags
:None
:InUse
:NoCollision
:NoGravity
:FaceCollision
|-
|valign="top"| <Physics>
|valign="top"| flag
| Optional tag for an Object.
:None
:Static
:Linear
:Animated
:Newton (used with <Flags> FaceCollision to [https://www.youtube.com/watch?v=YICB7qugrtc make an object pushable])
:: For a pushable object don't use import sub-tags such as animation name, flags, etc. Just use <Import Path="..." '''/'''> or <Import Url="..." '''/'''>
|-
| <Position>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z rotation.
|-
| <Scale>
| float
| Optional tag of Object. Only used for non-animated objects.
|-
|
<Import Path="...">

<Import Url="...">
|valign="top"| link
|valign="top"| This tag comes in two variants. It doesn't matter what variant you use.
|-
| <Animation Name="...">
| link
| File path to *.dae file.
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag of Animation. For more information on those flags look [[XML:OBAN|OBAN]] page.

;Object animation flags
:None
:Loop
:PingPong
:RandomStart
:AutoStart
:Local
|-
| <End>
| integer
| Optional tag of Animation. Frame number. Used to define the end of an OBAN from a *.dae file.
|-
| <Start>
| integer
| Optional tag of Animation. Frame number. Used to define the start of an OBAN from a *.dae file.
|}

The XML code for physics can be written in two styles.
*The '''first style''' mimics the original structure found in extracted ONLV instances. This makes it '''easier to edit old levels and reimport them''' into the game.
*The '''second style''' was created with structured data (nested objects) in mind and is '''suited for totally new levels''' where animated objects must be created in a 3D editor at first.

'''Code style 1'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
<Object>
<Geometry>M3GMDishBase.oni</Geometry>
<Animation>OBANDishBase.oni</Animation>
<Physics>Animated</Physics>
<ScriptId>201</ScriptId>
<Position>-197.729141 128.46283 -2501.46387</Position>
<Rotation>0.7071067 -1.545431E-08 1.545431E-08 0.7071068</Rotation>
<Scale>2.109375</Scale>
<Name>object_DishBase</Name>
</Object>
</Physics>
</Oni>

'''Code style 2'''
:For documentation purposes, the file here has been trimmed down.

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
[...]
<Object Name="motorcycle">
<ScriptId>8</ScriptId>
<Flags>FaceCollision</Flags>
<Import Url="motorcycle/export.dae">
<Animation Name="motorcycle02">
<Flags>AutoStart</Flags>
<End>880</End>
</Animation>
<Animation Name="motorcycle02_stop">
<Start>881</Start>
</Animation>
</Import>
</Object>
[...]
</Physics>
</Oni>

In this example, OniSplit takes the file "export.dae", looks at the parts it contains, and creates geometry files from it.
* M3GMhubs_rear.oni
* M3GMhubs.oni
* M3GMmotorcycle.oni
It's convenient that hierarchies are supported here.

The motorcycle is made of 3 parts so 3 object animations ([[XML:OBAN|OBAN]]) will be created up to frame 880. Then OniSplit creates 3 more OBANs starting from frame 881.

The reason for the interruption at frame 880 is probably to give Barabas a little more camera time in the cutscene.

;Notes about BSL usage:

The Vago Lab cutscene script uses the motorcycle objects and animations like this:
env_show 8 0 # hide static motorcycle parts or else they would be visible
env_show 9 0 # while Konoko is still riding her animated motorcycle
env_show 10 0 # the static motorcycle is separated into objects 8, 9 and 10

# Static and animated objects are totally independent from each other.
# They are stored in different arrays so their script IDs can use the same numbers.

obj_create 8 10 # create all animation-ready motorcycle parts
env_anim 8 10 # animate those parts (not necessary if OBAN flag is "AutoStart")

# The first animations would loop because of "AutoStart", so get the
# right timing to apply the other animations. "motorcycle02_stop"
# and the others will not loop because they don't have "AutoStart".
env_setanim 8 hubs_stop
env_setanim 9 hubs_rear_stop
env_setanim 10 motorcycle02_stop

obj_kill 8 10 # delete all animated parts
env_show 9 1 # show static motorcycle model where Konoko parks her bike

====Corpses.xml====
An empty Corpse element (<Corpse />) is treated as unused and placed at the end of the array. If no such empty elements are provided, OniSplit automatically adds 5. OniSplit also ensures that there are at least 20 corpses in the array.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Corpses>
|
|
|-
|valign="top"| <Corpse>
|valign="top"| -
|
|-
| <Class>
| link
| [[XML:ONCC|ONCC]]''name''
|-
| <Transforms>
| -
| There are 19 <Matrix> for each <Transforms> (which represents a body part).
|-
| <Matrix>
| matrix
| Float 3x3 + float x3 for the last 3 values (X Y Z position). For more information about the matrix, see [[OBD:CRSA]].
|-
| <BoundingBox>
| -
| Bounding box of the whole corpse. Optional; if not provided, OniSplit will generate an approximate one. Currently it doesn't try to locate the ONCC to compute an exact bounding box.
|-
| <Min>
| float x3
|
|-
| <Max>
| float x3
|
|}

'''Trimmed example'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Corpses>
<Corpse>
<Class>generic_male_1</Class>
<Transforms>
<Matrix>-0.36488995 0.04620622 -0.9299034 -0.05580434 -0.9980576 -0.02769538 -0.9293768 0.04178688 0.366759717 -215.667755 1.603917 92.85312</Matrix>
<Matrix>0.2961557 -0.185628444 0.936928 -0.368288517 -0.9272724 -0.06730227 0.8812806 -0.32512787 -0.342981815 -216.51889 1.64218426 93.189</Matrix>
<Matrix>0.407847315 0.156575248 0.8995248 -0.238757968 -0.9326179 0.2705892 0.8812805 -0.3251278 -0.342982143 -215.239883 0.8405094 97.23532</Matrix>
<Matrix>0.439697325 0.467113584 0.767118752 0.0248355754 -0.8601105 0.5095029 0.8978026 -0.204975232 -0.389789373 -213.6234 1.46109009 100.80056</Matrix>
<Matrix>0.717241049 -0.179043233 0.673430443 0.4761817 -0.579636 -0.6612664 0.5087397 0.794962764 -0.3304816 -214.81662 1.56564879 92.5172348</Matrix>
<Matrix>0.3398023 0.1672905 0.925498843 0.7910236 -0.5831365 -0.185023025 0.5087395 0.7949628 -0.330481827 -211.71907 0.792413354 95.42558</Matrix>
<Matrix>0.1283634 0.227430075 0.965297 0.804142356 -0.59352535 0.032904774 0.5804117 0.7720126 -0.259073079 -210.372269 1.45546341 99.0937653</Matrix>
<Matrix>-0.285799921 0.06851995 -0.955836535 -0.240357026 -0.970681965 0.00228381017 -0.927656651 0.230394751 0.2938901 -216.284851 1.5839076 91.29168</Matrix>
<Matrix>-0.312039882 0.04875436 -0.948817253 -0.176752359 -0.9842264 0.00755515043 -0.9334825 0.1700632 0.31573534 -216.689789 1.68287766 89.9359055</Matrix>
<Matrix>-0.356412441 -0.5390179 -0.763170958 0.0404523835 -0.82494843 0.5637587 -0.933452547 0.170058519 0.315826446 -217.422012 1.7979821 87.70907</Matrix>
<Matrix>-0.101782769 -0.247171819 -0.9636112 0.5426916 -0.8256094 0.154451028 -0.8337422 -0.507223248 0.2181709 -217.747284 1.30605173 87.0125656</Matrix>
<Matrix>-0.8154478 -0.150626346 0.558888733 -0.1200991 0.9885643 0.09119747 -0.566234052 0.00724477554 -0.8242127 -217.7402 2.065678 88.15346</Matrix>
<Matrix>-0.4593738 -0.326781839 0.825947642 0.8874048 -0.1284554 0.442732215 -0.0385793857 0.9363295 0.348996729 -219.093979 1.81561315 89.08131</Matrix>
<Matrix>-0.9545983 -0.13777709 0.26412034 0.295387268 -0.322961926 0.899134 -0.0385792255 0.9363296 0.348996431 -220.3681 0.9092429 91.37218</Matrix>
<Matrix>-0.9715769 -0.0362956524 0.233924776 0.0276728421 -0.9988148 -0.0400396362 0.2351007 -0.0324283168 0.9714299 -222.775482 0.56178683 92.03825</Matrix>
<Matrix>0.979860842 -0.192433611 0.0533096045 0.193336874 0.9810555 -0.0122905634 -0.0499345176 0.0223497637 0.9985025 -216.8387 1.90143847 87.84845</Matrix>
<Matrix>0.863898 -0.399280578 0.3070101 0.171117 -0.340619326 -0.9244986 0.4737078 0.851207137 -0.225936681 -215.211975 1.58196676 87.93695</Matrix>
<Matrix>0.4673251 -0.0255063027 0.883717656 0.746463835 -0.524209559 -0.4098731 0.4737075 0.851207256 -0.225936785 -212.815842 0.47451216 88.78848</Matrix>
<Matrix>0.216871262 -0.007893051 0.976168454 0.3751846 0.9238389 -0.0758833 -0.9012231 0.3827002 0.203315422 -211.637314 0.410188764 91.0171051</Matrix>
</Transforms>
<BoundingBox>
<Min>-219.731216 -2.258905 84.47974</Min>
<Max>-207.518463 4.49535131 104.023239</Max>
</BoundingBox>
</Corpse>
</Corpses>
</Oni>





[[Category:Modding tutorials]]

Creating a level

2025-01-22T03:48:45Z

Vortice: /* Fan-made levels */Fixed broken forum links to archive links.

This page covers level creation from scratch. See [[Modifying an existing level]] if you want to change a vanilla level in the game.

==Level releases and resources==
===Fan-made levels===
{| class="wikitable sortable autosort by-column-3"
!Date
!Name
!Level number
|-
|TBA
|Oni 2 Angel Studios Tour
|32
|-
|TBA
|Green Room
|26
|-
|2019/09/16
|[https://web.archive.org/web/20240527004257/http://oniforum.bungie.org/viewtopic.php?id=2965 Omega Tournament]
|31
|-
|2016/02/13
|[https://web.archive.org/web/20160224173743/http://oni.bungie.org/forum/viewtopic.php?id=2947 AI Battle]
|7
|-
|2014/01/19
|[https://web.archive.org/web/20211202225410/http://oni.bungie.org/forum/viewtopic.php?id=2698 Wilderness Preserve]
|17
|-
|2013/09/07
|[https://web.archive.org/web/20201127180732/http://oni.bungie.org/forum/viewtopic.php?id=2656 Island]
|29
|-
|2013/07/12
|[https://web.archive.org/web/20201127175459/http://oni.bungie.org/forum/viewtopic.php?id=2640 City]
|28
|-
|2013/06/01
|[https://web.archive.org/web/20201029102326/http://oni.bungie.org/forum/viewtopic.php?id=2619 Fight Club]
|25
|-
|2012/05/12
|[https://web.archive.org/web/20220701102842/http://oni.bungie.org/forum/viewtopic.php?id=2357 Old China]
|24
|-
|2012/03/18
|[https://web.archive.org/web/20211202220454/http://oni.bungie.org/forum/viewtopic.php?id=2302 Boss Battle]
|23
|-
|2012/02/12
|[https://web.archive.org/web/20201029113554/http://oni.bungie.org/forum/viewtopic.php?id=2271 De Dust Deluxe]
|22
|-
|2012/01/23
|[https://web.archive.org/web/20201029114415/http://oni.bungie.org/forum/viewtopic.php?id=2242 Parkour Challenge 2]
|21
|-
|2012/01/16
|[https://web.archive.org/web/20211205145843/http://oni.bungie.org/forum/viewtopic.php?id=2235 Parkour Challenge]
|21
|-
|2011/07/25
|[https://web.archive.org/web/20201029103607/http://oni.bungie.org/forum/viewtopic.php?id=2001 Mini-Partenon]
|5
|-
|2011/10/03
|[https://web.archive.org/web/20201029113340/http://oni.bungie.org/forum/viewtopic.php?id=2024 Muro's Lair - Preview]
|20
|-
|2011/07/03
|[https://web.archive.org/web/20201029113724/http://oni.bungie.org/forum/viewtopic.php?id=1957 Hexagon]
|16
|-
|2011/06/23
|[https://web.archive.org/web/20201029104928/http://oni.bungie.org/forum/viewtopic.php?id=1938 Junkyard]
|15
|-
|2011/05/01
|[http://mods.oni2.net/node/178 Arena of Hurt (OZG)]
|7
|-
|2010/11/08
|[https://web.archive.org/web/20210117150652/http://oni.bungie.org/forum/viewtopic.php?id=1736 Arena of Hurt (OTA)]
|7
|-
|2010/11/06
|[https://web.archive.org/web/20201029105217/http://oni.bungie.org/forum/viewtopic.php?pid=50565#p50565 Martian Colony] AKA "Silly World"
|5
|-
|2010/02/15
|[https://web.archive.org/web/20201029113916/http://oni.bungie.org/forum/viewtopic.php?id=1506 Maze]
|5
|-
|2008/09/16
|[http://mods.oni2.net/node/4 Arena of Pain]
|30
|-
|2024/05/20
|[https://gamebanana.com/mods/514707 Kitsune: Chapter 1]
|20
|}

===Forum tutorials on level creation===
* '''[http://oni.bungie.org/forum/viewtopic.php?id=2087 "Creating the Lair - A level tutorial"]'''
* [http://oni.bungie.org/forum/viewtopic.php?pid=53026 "Creating a Custom Oni Level (s10k video tutorials)"]
* [http://oni.bungie.org/forum/viewtopic.php?id=1515 "Creating new levels"]
* [http://oni.bungie.org/forum/viewtopic.php?pid=33838 "Create levels with pathfinding grids"]
* [http://oni.bungie.org/forum/viewtopic.php?id=2000 "More questions about levels"]
* [http://oni.bungie.org/forum/viewtopic.php?pid=37252#p37252 "Modding Existing levels - Beta" ("Moveable furniture" post)]

===Wiki pages on level creation===
* [[Creating a level]] (you are here)
* [[Modifying an existing level]]
* [[New levels]]
* [[Lightmapping levels]]

===Free asset sources===
* [http://vk.com/gameready Various game meshes]
* [http://web.archive.org/web/20230601050258/http://tutorialsforblender3d.com/Textures/Textures_index.html Various game textures]
* [https://www.textures.com Various game textures]

==Engine limitations==
First you should be aware of the limitations that Oni will place on your level.

* The triangle limit of a game level is approx. 520,000 (consider it 500,000 to be on the safe side).
* {{ModTool}} can save DAE files with a maximum of 64,000 triangles per object.
* When polygons are too tightly packed, the camera will look at too many of them and glitches will appear. The limit on visible GQs (Gunk Quads) is 8,192 (213), and higher numbers will cause render bugs and produce the console error message "Exceeded max visible GQs ''number''". There are limited solutions to this:
** Decrease the '''gs_farclipplane_set''' value.
** Hide objects via '''[[#.3CModel.3E|env_show]]'''.
** Hide objects by ''level design''. For example, departments in a building could be quite detailed because the view of the other departments/rooms is blocked by walls.
* The camera can look at 2,049 transparent textures at once; one more, and Oni crashes.
* Characters are visible ''only'' within world coordinates {-4,099, -4,099, -4,099} to {4,099, 4,099, 4,099}.
* Geometry stops outside of (roughly) world coordinates -4,228 to 4,228 on the X and Z axes (vertical axis not tested).
* '''chr_debug_spheres = 1''' visualizes the collision spheres of characters, so you can check if they will fit through an entrance.

==3D tools==
===Problems when using multiple different tools===
Re-saving a DAE file in '''Mod Tool''' which was originally made in '''SketchUp''' can result in a surprising change in size within Oni. This is due to a difference in the specification of a scale unit.

: For example, the SketchUp DAE file may have: <tt><unit meter="0.0254000" name="inch" /></tt>
: And the re-saved Mod Tool DAE file may have: <tt><unit meter="0.1" name="decimetre"></unit></tt>

In that case you'll need to open the new DAE in a text editor and change the length specification back.

===Sketchup===
If you are working with Sketchup check out this pages:
* [http://oni.bungie.org/forum/viewtopic.php?id=2003 "Sketchup tutorials for making levels"]
* [[SketchUp tutorials and tips]]

===Blender===
'''Scaling'''

Same as Mod Tool and SketchUp: Caution with scaling: See [[#Problems when using multiple different tools|here]]

'''Pathfinding'''

Be sure to uncheck automatic triangle creation when exporting (BNV) geometry used for pathfinding. Ghost (''doors'') must be quads.

==Setting up a workflow==
If not noted differentely you need OniSplit v0.9.82.0 or a newer version. Onisplit can be downloaded [http://mods.oni2.net/node/38 HERE] (it also comes with the [[AE]] and is found in the Tools directory of the installation).

The level import demo files can be downloaded [http://mods.oni2.net/node/299 HERE].

First, put '''OniSplit.exe''' into the second '''lab''' folder alongside the XML files.

Look at the file '''build.cmd'''. These are the two important lines:

OniSplit.exe -create:level out lab.xml
OniSplit.exe -import:pc out level3_Final.dat

The first line creates the *.oni files from a master.xml file, in this case '''lab.xml'''. Once finalized, the resulting .oni files can be put into a new [[Making a mod package|AE package]].

The second line creates level archives which can be used for fast tests. They don't require you to install a package through the AE Installer.

Instead of "-nosep" you can now also use "-pc" for the import. Macs, however, do use "-sep".

==Troubleshooting==
If the game crashes while loading at ~90% progress, be sure that the texture's x and y dimensions are powers of two: 64, 128, 256, 512….

If the game crashes while loading at ~50-60% progress, be sure that the BINACJBOCharacters or AISA file has a player character defined.

If the game crashes while loading ~5-10% progress, check if all your textures were inside the "out" folder.

:You can extract the AKEV file to XML, then search for the [[XML:AKEV#TXMA|TXMP Array]].

:[http://mods.oni2.net/system/files/AKEV_texture_checker.txt THIS] script checks which textures are missing by comparing the AKEV*.xml with its *.oni files folder. Change the two paths so that it works for you: Alt+4, insert code, then F5.

"TXMP_marker_door" and "TXMP_marker_ghost" will be missing in the demo's "out" folder.

You can add this between the other two lines in build.cmd to prevent a crash.
OniSplit.exe -create:txmp out env/markers/*.tga

==Terminology==
;Polygon
:A polygon is a shape defined by points (vertices) in space. Polygons are the most fundamental building block in games. Oni uses only shapes with 3 and 4 points (triangles and quads). Other games might also use N-gons, shapes with more points.
;Face
:The '''surface of a polygon''' is also named face. The '''direction''' of a face in '''defined by its normal'''. If an object seems to have a hole, it might be that the polygon just has a '''flipped normal''' and is therefore wrongly rendered (displayed on screen).
;Normal
:Faces and even vertices themselves have directions. The normals of vertices determine how smooth or sharp edges will appear.
;Vertex (plural<nowiki>:</nowiki> vertices)
:A point within a polygon.
:Vertex colors radiate from one vertex to another vertex, whereby their different color values blend into each other so that gradients can appear.
;Edge
:A line of two points within a polygon.
;Tris (triangles)
:Polygons made of 3 points.
;Quads
:Polygons made of 4 points. Planes. Rectangles.
:Internally, all quads get converted into two triangles and will affect the maximum triangle count accordingly.
;Level
:The term "level" is often used to shorten "level map" (buildings and terrain).
;Geometry
:Level geometry can be objects made of tris and/or quads.
:Oni differentiates between basically 3 types of level geometry:
:* Static objects (sometimes also named AKEV core geometry)
:* Animated objects
:* Pushable objects (not used in the original game)
;Static geometry
:* '''Unique level geometry with no functions''' (AKEV core geometry such as buildings and streets).
:* '''Repeating objects''' are flagged as '''furniture (FURN)''' although they can be outdoor objects such as boxes and containers. FURN objects were used to be imported by an object collection, an CJBO. Nowadays, furniture collections can be used (again) for imports, but the individual objects are stored as OFGA files. This modularity is known in many game editors (like the Unreal Engine Editor). So, '''OFGA are nothing else than "game assets".''' The drawback of OFGA is that they '''will not import with any vertex shading'''. Only their '''geometries''', attached '''particle''' and '''gunk flags''' get copied into final (baked) level geometry.
:* '''Objects with actual functions''' (CJBO such as doors, consoles, triggers)
:** Some types of CJBO (spawn lists of weapons, characters, powerups and of course flags and patrol paths) are not considered as level geometry.
;[[XML:AKEV#AGQG|Gunk flags]]
:Properties directly associated with the polygons. Among others, these can be: Transparent, TwoSided, NoCollision, Invisible, NoObjectCollision, NoCharacterCollision, NoDecals, Furniture, Impassable.
;Baking
:When a level gets baked, all geometries get merged.
:*Unique level geometry will have vertex painting.
:*Objects derived from already compiled oni-files (shared classes) will have no vertex painting.
:*Animated and pushable objects will have no vertex shading.
;Vertex shading
:Vertex colors (vector data) can be painted onto core geometry.
:They are used as a rudimentary form of lightmapping (pixel data).
:Having vertex shading is still better than having no vertex shading at all. It makes the level appear more lifelike.
;Lightmapping
:In other games, lights and shadows are added to level geometry with lightmapping.
:There were experiments to bring lightmaps back to Oni. The technique come with a major drawback though. It doubles the triangle count and adds many textures.
;In-game
:When you are "inside" the game, running or playing it.

==Level construction==
'''Visible environment'''
* A '''level map''' consists of visible geometry: terrain and buildings. This is also named the '''environment''' or for short '''env'''.
** Use '''quads''' of approximately 10 up to 20 meters in size to construct env geometry.
* Anything other than floors and simple walls will be made of triangles.
** Geometry from CJBO works best with triangles. Quads might show holes in-game.
'''Invisible pathfinding'''
* '''AIs''' (or non-player characters, NPCs) need '''pathfinding''' data, usually shortened as '''bnv'''.
** Pathfinding data can be described as geometry, therefore as rooms. These '''bnv rooms''' are made of '''floors''' and are connected by '''ghost''' quads which work like doors. AIs can move from one room to another room only by passing a ghost. Therefore, ghosts have the same width as rooms in open terrain.
*** Use floor quads of approximately 10 meters in size to construct BNV floors.
*** Put ghost quads exactly on the edges of BNV floors with an angle of 90 degree.
'''Support for [[XML:BINA/ONIE|effects]]'''
* Effects such as decals that indicate damaged environment need level textures to be registered in [[XML:BINA/TMBD|TMBD]]. Make sure not to replace existing texture entries but to add your own so that the other levels remain unaffected.
'''Level logic'''

BSL scripts bring levels fully to life. The logic is mostly event driven whereby different checkpoints and conditions must be reached.
* Checkpoints are actually [[XML:BINA/OBJC/TRGV|trigger volumes]] that can recognize entering and exiting characters.
* The second most important source of events are [[XML:BINA/OBJC/CHAR|character (script) functions]], especially the die function of enemies.
** To support good and less good players alike, NPC characters can feature the UpgradeDifficulty flag. Also, BSL scripts can detect the current [[BSL:Game_status|difficulty level]].
* [[XML:BINA/OBJC/TRIG|Laser triggers]] are mostly used to control [[XML:BINA/OBJC/TURR|turrets]]. [[XML:BINA/OBJC/CONS|Consoles]], triggers and [[XML:DOOR|door]] unlocking are used to set up very simple "riddles”.
* The creation of cut scenes is time-consuming quality work. Due to missing tools for streamlined workflows, it is totally okay for you to skip this.
** New synchronized FILM, OBAN and TRAM files are required for cut scenes. Not to mention sound files for dialog.

==The master XML file==
''The project file for level creation.''

The '''master XML''' file's '''name determines''' the '''BSL folder name''' and the '''AKEV and ONLV file names''' in the output folder. File paths in the XML can be either absolute or relative.

'''Mandatory files''' for level import:
* ''level_environment''.dae
* ''level_bnv''.dae
* ''level_textures.tga/jpg/png''
* Character.xml or AISA with player
* ONSK name in <Sky> (in Windows, this can be a fake name; does the Mac need actual ONSK files?)
* ONLD file for the new level; read [[Making_a_mod_package#Mod_Info.cfg|HERE]] about making sure your level is unlocked (accessible on the Load Game screen)

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
|valign="top"| <Level SharedPath="...">
|valign="top"| link
| The master XML file can link to other XML files. Most of them will be [[OBD:BINA/OBJC#OBJC_types|BINACJBO]] files. The file type is declared inside the file, so the file name itself doesn't have to contain the type. Ergo, "BINACJBOCharacter.xml" can be given a simpler name like "Character.xml".

Some resources used by those XML files can be found in a '''shared''' folder. OniSplit copies textures and "physics" objects into the output folder; furniture objects will be integrated into the AKEV. Unused resources in the shared folder will be ignored. That way the final level archive or AE package contains only the necessary files, saving disk space for the end user.

In the demo are various subfolders in the '''shared''' folder: consoles, doors, furniture, triggers and turrets. These file types do not need their file prefixes: CONS, DOOR, TRIG and OFGA. OniSplit will recognize them nonetheless.

'''Common mistake:'''

CJBO files '''need relative paths to the resource instead of just file names'''. Taking consoles, for example: a standard export to XML gives you "console_data". But to use the shared resources these must be paths like "'''consoles/console_data.oni'''" as they are stored in '''shared/console/'''. Note how the demoed '''shared''' folder is placed next to the [http://mods.oni2.net/node/299 project ("lab")] folder and the XML master file points to it using "../shared".
|-
| <Environment>
| -
|
|-
| <Model>
| -
| Used to import level geometry and static objects. See [[#<Model>|HERE]] for detailed information.
|-
| <Import Path="..."/>
| link
|
|-
| <Node Id="...">
| string
| informational (space for notes)
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Can be used with BSL commands such as ...
: [[#<Model>|env_show ID 1]] (use 0 to hide)
: [[#Breakable glass with BSL recognition|env_broken ID1 [ID2]]] (if a second ID is supplied then objects in the range ID1..ID2 get counted; "3001 3018" would cover 18 objects)
: [[#Texture exchange|env_texswap ID texture]] (no file prefix/suffix allowed)
: [[#env_shade|env_shade ID ID R G B]]
Static objects store their ID in [[XML:AKEV#IDXA_.28quad_group_id.29|one of AKEV's IDXA instances]].
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
|valign="top"| <Rooms>
|valign="top"| -
| For detailed information see [[#<Rooms>|HERE]].

For a Google SketchUp BNV tutorial see [http://oni.bungie.org/forum/viewtopic.php?pid=36760#p36760 HERE].
|-
| <Import Path="..."/>
| link
| File path to *.dae file. BNV data, used to create pathfinding.
|-
| <Textures> {{Anchor|textures_tag}}
| -
| With OniSplit v0.9.94.0+ you can use attributes to set the default import formats and max dimensions. For example:

: <Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">

Textures with a dimension that isn't a power of two (2x) and textures larger than 512px on a side will be resized. For example, 2003x2000 will become 512x512. (What would 257x255 become?)
|-
| <Texture Name="...">
| string
| TXMP file name to generate.
|-
| <Flags>
| flag
| Optional tag. For list of flags see [[XML:TXMP|HERE]].
|-
|valign="top"| <Format>
|valign="top"| flag
|
:DXT1
:BGR
:RGBA
:BGR555
:BGRA5551
:BGRA4444
|-
|valign="top"| <GunkFlags>
|valign="top"| flag
|
;AGQG (Gunk) flags (trimmed list)
see ''OniSplit -help enums'' for more flags
:None
:NoCollision
:NoObjectCollision
:NoCharacterCollision
:NoDecal
:TwoSided
:Invisible
|-
| <Image>
| link
| File path to *.tga/jpg file.
|-
|valign="top"| <Sky>
|valign="top"| string
| ONSKfile.oni (without file pre- and suffix)

The import doesn't work with an empty tag. <Sky>clear</Sky> helps here; any other fictional name will also do.

For detailed information see [[XML:ONSK|HERE]].
|-
| <Objects>
| -
|
|-
|valign="top"| <Import>
|valign="top"| link
| File path to an OBJC (collection) file. Supported collection files for <Import> are:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[#Furniture.xml|Furniture.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[#Physics.xml|Physics.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

The following two collection files are '''NOT''' supported. You need to copy them as regular pre-compiled *.oni files into your mod package:
: [[XML:BINA/OBJC/MELE|Melee.xml]] (overrides global MELE; not used in vanilla levels)
: [[XML:BINA/OBJC/CMBT|Combat.xml]] (overrides global CMBT?; not used in vanilla levels)

'''Inside''' the following three supported collection files, provide links to pre-compiled (*.oni) class files: console, door and furniture collections. Use relative paths such as:
:: <code>'''consoles/'''console_data'''.oni'''</code>
:: <code>'''doors/'''TCdouble'''.oni'''</code>
:: <code>'''furniture/'''V_tctf_bigvan'''.oni'''</code>

When you are unsure about the folder structure refer back to the [http://mods.oni2.net/node/299 level import demo].
|-
| <Films>
| -
|
|-
| <Import>
| link
| File path to *.xml file. OniSplit creates a [[XML:FILM|FILM]] file from it. Used for characters in cutscenes.
|-
| <Cameras>
| -
|
|-
| <Camera Path="...">
| link
| File path to *.dae file. OniSplit creates an OBAN file from it. Used for cutscenes.
|-
| <Animation Name="..."/>
| string
| Name for the OBAN file.
|}

This is a trimmed-down version of the master file '''lab.xml''' from the demo. It's meant to give you a first impression. We might upload a smaller demo someday with all features nonetheless.

<?xml version="1.0" encoding="utf-8" ?>
<Oni>
<Level SharedPath="../shared">
<Environment>
<Model>
<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_bomber_window.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>
</Model>
<Rooms>
<Import Path="env/lab_bnv.dae"/>
</Rooms>
<Textures>
<Texture Name="GOO">
<Format>bgra4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>
</Environment>
<Sky>sunset</Sky>
<Objects>
<Import>Character.xml</Import>
<Import>Furniture.xml</Import>
<Import>TriggerVolume.xml</Import>
<Import>Physics.xml</Import>
</Objects>
<Films>
<Import>films/BomberKonRun01.xml</Import>
<Import>films/BomberKonRun02.xml</Import>
</Films>
<Cameras>
<Camera Path="cameras/BomberCam01.dae">
<Animation Name="BomberCam01"/>
</Camera>
<Camera Path="cameras/BomberCam02.dae">
<Animation Name="BomberCam02"/>
</Camera>
</Cameras>
</Level>
</Oni>

===<Model>===
This tag is mandatory (it must be present to avoid errors); the model section contains one import path to the AKEV (level) geometry (*.dae) and can contain additional import paths for exceptions (*.dae).

Data from the demo:

<Import Path="env/lab_env.dae"/>
<Import Path="env/lab_motorcycle.dae">
<Node Id="motorcycle">
<ScriptId>9</ScriptId>
<GunkFlags>NoCollision</GunkFlags>
</Node>
</Import>

'''env_show'''

The motorcycle has here scripting ID 9. You can show and hide the object with the BSL command '''env_show''', where the second parameter means true or false. '''Never use 0 as an ID''' because it won't work.

env_show 9 1
env_show 9 0

EdT demonstrates env_show [https://www.youtube.com/watch?v=Em6wa5JTQNM here]. Note how the objects have collision.

The last vanilla level (Syndicate Mountain Compound) has a big satellite dish platform that can be made hidden. Obviously, such objects/areas can be made to have pathfinding too.

;More possible applications of env_show:
* ground/ceiling/objects for cutscenes that become partially destroyed
* destructible walls like in Deus Ex: Human Revolution (trigger volume, replacing punch anim with punch-through-wall anim)
* grids in front of ventilation shafts (a small door object could be an alternative)
** at the moment this can't be done because characters can't sneak under the top edge of the opening (the characters collision spheres are too big)
* managing object groups with trigger volumes (save multiple objects in one DAE file)



====Import of object groups====
'''Mod Tool versus SketchUp'''

The meaning and behavior of "groups" greatly differs in these two programs.

:'''In SketchUp''' you can group objects which enables you to easily duplicate all objects inside a group and to scale/rotate/translate them all together.

:'''In Mod Tool''' grouped objects are still loose, and duplicating a group won't duplicate the objects. To achieve the same effect as in SketchUp, you have to create a hierarchy where any one object is the "parent" and all others the "children".

'''Google SketchUp'''

To create a group, select two or more objects, right-click on the selection and choose "make group".

[[Image:ModTool_can_import_objs_in_hierarchies.jpg|right|thumb|Mod Tool can import objects in hierarchies to Oni.]]
'''Mod Tool'''

Either use the Explorer (A) or the Schematics (B) to create a hierarchy.

:(A) In the Explorer window, drag and drop one or more objects onto another one.

:(B) Open the constrain tab at the right side. Select parent object, click "Parent", click the child object(s). Check the result in the Schematics window.

:'''Mod Tool: caution when saving to DAE!'''

:A normal selection won't do. You have to select the object tree to successfully save a hierarchy. This is the same way that you do it with Oni characters.


====Breakable glass with BSL recognition====
Broken environmental objects can be recognized by the BSL command ''env_broken (ID_1, ID_N)''. However, this requires additional code to work.

An example is the training level. Let's determine how we can set up such a thing.

First we need a [[XML:BINA/OBJC/TRGV|trigger volume]] like in level 1.

<TRGV Id="11495">
<Header>
<Flags>Locked</Flags>
<Position>-714.6615 -298 -555.2073</Position>
<Rotation>0 0 0</Rotation>
</Header>
<OSD>
<Name>tv75</Name>
<Scripts>
<Entry></Entry>
<Inside>targets_gone</Inside>
<Exit></Exit>
</Scripts>
<Teams>255</Teams>
<Size>400 31 270</Size>
<TriggerVolumeId>75</TriggerVolumeId>
<ParentId>0</ParentId>
<Notes></Notes>
<Flags>PlayerOnly</Flags>
</OSD>
</TRGV>

Now we need some BSL code.

var int inside_target_function;

func void enter_target_function(void)
{
dprint enter_target_function
inside_target_function = 1;
}

func void exit_target_function(void)
{
dprint exit_target_function
inside_target_function = 0;
}

func void targets_are_not_gone(void)
{
# CB: turn off the trigger volume and sleep for a second
# so as not to cause hideous performance loss
trigvolume_enable tv75 0
sleep 60
trigvolume_enable tv75 1
}

func void targets_gone(string ai_name)
{
if (inside_target_function eq 0)
{
enter_target_function() # catch other "targets_gone" functions to let them do nothing

var int num_broken = env_broken(3001, 3018);
# if you only one target use scheme: env_broke(3001, 3001)

if (num_broken eq 18)
{
targets_are_gone();
}

if (num_broken < 18)
{
targets_are_not_gone(); # to set check interval to one second
}

exit_target_function
}
}

func targets_are_gone
{
trigvolume_enable tv75 0
# [...]
}

;Explanation:

Player enters the TV, targets_gone() gets triggered. The variable "inside_target_function" should be 0 by default, so we will enter the "if" block. Next, we can assume that the player didn't destroy all glass objects, so "num_broken" will be less than 18; thus, targets_are_not_gone() gets called.

The TV function targets_gone() ''would'' be triggered every frame, but targets_are_not_gone() creates a delay between checks: the TV gets deactivated for 60 frames. Then the TV becomes enabled again and will start anew until all glass objects got destroyed or player left the TV.

In this case the targets_gone() function will do nothing because "inside_target_function" was set to 1 by the first call.

targets_are_gone() eventually disables the TV to prevent memory overflow; this function also contains all the things ("[...]") that you want to happen after the glass target is broken.

====Texture exchange====
BSL command supported on Windows and Mac:
: env_texswap ID texture

Might be useful to switch on/off static and animated textures. (News broadcast screen: running or off or smashed. Lava stream: flowing or stagnating or cooled down. Etc.)

A similar effect can be achieved by showing/hiding geometries with different textures as EdT has demonstrated in a private test. That way it should also be possible to have different vertex coloring for an area.

====Vertex coloring====
Vertex colors can be edited manually in Blender by setting up following 3 things:
* Properties Panel > Data > Color Attributes
* 3D viewport (left top) > change work mode to Vertex Paint
* 3D viewport (right top) > change to Viewport Shading to Solid mode (under the dropdown menu you can choose "flat" to have full saturation)

{{divhide|Mod Tool}}

[http://web.archive.org/web/20170529111607/http://softimage.wiki.softimage.com/xsidocs/tex_vcolor_CreatingColoratVerticesCAVMaps.htm SoftImage documentation.] Observation: The sniper tower from level 19 Syndicate Mountain Compound can be isolated and re-imported as it is. It will appear quite dark.

If we remove "_color" from the object, the shadows will be gone next time we import the tower.

Mod Tool: Explorer [8]

Object
|
+-- Polygon Mesh
|
+-- Cluster
|
+-- Polygon
| |
| +-- [...]
|
+-- NodeProperties
|
+-- '''_color'''
+-- texcoord (Explicit UVWs)
|
+-- Vertex_Color_Def

So, how do we modify that data?

'''Single object shading'''

If there's already a vertex color property, you can use Shift + W to activate the Paint Vertex Color Tool. With Control + W you can change the brush color. R + Hold Click + Move Mouse let you change the brush size. The more vertices (points) you have, the more detailed you can make the shadows/colors. But keep in mind that too many polygons can destroy collision, making characters fall through the ground.

If there's no vertex color property, the first usage of Shift + W will create that property. But you can also manually create it via Property > Color under Vertices Map.

'''Level-wide shading'''

[[Image:light_test_modtool.png|right|thumb]]
[[Image:light_test_ingame.png|right|thumb]]

To get general shading/lighting you can set up light sources. "Infinite" lights are useful for global lighting, while "Light Box", "Point", "Neon" and "Spot" are more suitable as local light sources. They can be accessed via Primitives > Light.

By default, a Mod Tool scene has one Infinite light, but it doesn't shine in every direction so you might want to add more Infinite lights. Let's say one Infinite light for each direction (+X, -X, +Y, -Y, +Z, -Z) with an intensity of circa 0.25 (night) or 0.75 (day).

The illumination of those lights can be integrated into the vertex color property. There's some information [http://oni.bungie.org/forum/viewtopic.php?pid=29089#p29089 on OCF here]; the quoted information is in triplicate, so don't get confused by that: at first it's detailed, then summarized, then as a checklist.

Basically, you can go with the checklist:

* Property > Color At Vertices Map
* Property > Render Map
* In render map property page, under Sampling select Vertices Only
* Under Surface Color, choose Enable, then in the box below select Vertex _Color; if that option does not appear, click on the New button next to it
* Under Map, select Illumination only
* Finally, click on the button Regenerate Maps...

This must be done for all objects separately.

: [http://mods.oni2.net/system/files/vertex_color_script.txt There's a script here] which can apply vertex color and render maps to all '''selected''' objects. Load it into the script editor with Alt + 4 and hit F5 to run it. (Be sure the script's language was set to VBScript.)
: The variable "overwrite_VC" can be changed.
:: With "1" all existing CAV maps of selected objects will be overwritten. This can take some time.
:: With "0" only selected objects without CAV maps will be the script's target.

'''Notes on ModTool view modes'''
* "Constant" let you see the colors of the vertex coloring only.
* "Textured Decal" let you see object textures only.
* "Shaded" let you see the illumination only.
* "Textured" let you see the textured object with illumination and vertex coloring.
{{divhide|end}}

=====env_shade=====
If you use '''env_shade''', use it with caution. It completely overwrites the vertex coloring.

# BSL command
# env_shade obj_id obj_id R G B

# examples
env_shade 7 7 # object 7 will be black
env_shade 7 7 0 0 0 # object 7 will be black
env_shade 7 7 .31 .999 .5 # object 7 will be quite green
env_shade 7 10 1 1 1 # object 7, 8, 9, 10 lose all their shading

====Baked lightmaps====
A drawback of this method, AKA shadow maps, is the high number of [[XML:BINA/TMBD|TMBD]] changes and new textures for every wall, requiring a lot of memory. How to create shadow maps:

* https://web.archive.org/web/20121105081823/http://www.game-artist.net/forums/support-tech-discussion/5622-burning-shadows-onto-texture-xsi.html


Notes on map options:
* "Surface color and illumination": outputs used texture with added shadows
** Can be used to replace original texture
* "Illumination only": output a texture that only contains the shadows
** Can be used on a new overlying, transparent surface

====Standalone lightmaps====
With this approach there are two meshes, whereby the shadow effects on one mesh get drawn in front of the regular level texture.

Compared to the "baked lightmaps" method, this needs more polygons of course. And these polygons are transparent, which is a problem with Oni's limited rendering ability for such textures. However, standalone lightmaps only need a few new textures if used wisely.

Read [[Lightmapping levels]] to learn more.

[[Image:Oni_Lightmaps_double_polygon_method.jpg|center]]

===<Rooms>===
The Rooms tag is mandatory. It contains an import path to BNV and ghosts (*.dae) which are used to create pathfinding grids. For information on the binary data behind this, see [[OBD:AKVA|HERE]].

Sample code from the master XML file:
<Import Path="env/lab_bnv.dae"/>

'''Fundamentals'''
* '''BNVs''' are '''volumes''' (sometimes also named '''rooms''') that have a pathfinding grid assigned to them.
* For practical reasons you only need '''floors and ramps''' to build a BNV. (As seen [http://edt.oni2.net/images/Hideout_BNV.jpg HERE.])
** A BNV polygon can consist of 3 or more points, but it's recommended to use '''shapes with 4 points''' because the other shapes usually waste more grid space. At the moment you can import only '''[[wikt:convex|convex]]''' shapes.
* Secondly, there are so called '''ghosts''' (vertical quads) that connect '''neighboring BNVs'''. AI can only transit from BNV to another through ghosts.
: OniSplit gives error messages for ghosts that don't have 2 neighboring BNVs, for example:
BNV Builder: Ghost 'grid2' has no adjacencies at <-72,41 1,999 -166,6> and <-71 1,999 -168,21>, ignoring

'''Tolerance values'''
* Horizontal distance from room to ghost: 1
* Vertical distance from room to ghost: 18
* Ghost's horizontal dimension must be greater than 0
* Under optimal circumstances, pathfinding works on a plane that is +4 world units above or -0.5 below the pathfinding grid
* Normally characters can't pass over low vertical walls such as stairs/curbs if those don't have a ramp under them; near ground level (Y=0) is an exception where characters are allowed to step on a plane that is 4 world units above pathfinding grid; higher planes need a ramp
* Maximum angle of ramp you can go on is 70°; higher angles will make characters fall through to their death (in those cases you might want to add invisible walls/boxes to prevent them from touching the ramp)

'''More notes on PF processing'''
* Actually, BNV and ghosts can have any name and don't need any texture.
* During pathfinding calculation, OniSplit creates a new folder called "temp" and a subfolder "grids". There is a file named "''levelname''_grids.dae". That file contains rooms with textures called "bnv_grid_''N''.tga" which mark obstacles in the pathfinding grid. Ghosts will have a transparent texture "'''_marker_ghost'''.tga". You also get these when you export a level. Transparent ghosts make it easier to see the rest of your level if you have many of those planes.
* In Mod Tool, ghosts and rooms can be grouped under a null object. Right-click the null object to select all its children, then use "Selection Only [x]" as your saving option. That way all the planes can be quickly saved to a *.dae file.
* You can influence the pathfinding creation of dangerous zones using danger quads. Read about those [[#Marker textures|HERE]].
* Another kind of influence is the [[#<Model>|gunk flag]] IgnoreGrid. It can be used to tell OniSplit to ignore the object during pathfinding creation. The grids in that place will be white.

[[Image:Pathfinding_grid.jpg|thumb|200px|right|'''ai2_showgrids = 1''' in action]]
'''BSL commands'''
* chr_show_bnv = 1
:: shows number of BNVs the player is standing on
* ai2_showgrids = 1
:: shows pathfinding grids
* ai2_chump
:: spawns a friendly Striker that follows the player if possible, makes also pathfinding grids visible
* ai2_chump_stop = 1
:: Striker stops following you
* ai2_chump_stop = 0
:: Striker follows you again

====Pathfinding on uneven ground====
Pathfinding works on slightly uneven ground as long as the polygons are 0.5 world units beneath or 4 world units above the BNV.

For greater surface irregularities, we can use a trick:
* The problematic polygons must be saved to a DAE file and then referenced in the model section as an individual object.
* Then the <GunkFlags> tag needs to be '''''GridIgnore'''''.
* Additionally we create a plane (invisible if necessary) under the object so that Oni doesn't think there's a hole.
* The ghosts must be taller than the highest polygon to be walked on. (This has been tested up to a height of 2,000 world units.)

'''Symptoms of too-small ghosts'''

A) AI can't run at all.

B) AI loses PF ability if the tracked enemy performs animations that are outside of the pathfinding volume. Here's a video (<nowiki>https://youtu.be/vfKPzP5hiCo</nowiki>, dead link) showing these symptoms.

'''Missing boundaries'''

Let's say you have a BNV, tall ghosts, and a GridIgnore-flagged hill with trees and bushes and stuff.

Why do AIs run up against the trees?
: '''Problem:''' There are no red/orange grids that limit the AI's movement. Normally, objects will produce red pathfinding squares around them. But objects that are 20 world units above the BNV are ignored just like objects with the IgnoreGrid flag.
: '''Solution:''' Add simple geometries like ''_marker_impassable fences'' or danger quads near the BNV.

'''Disappearing AIs'''

The ground is sometimes not solid, and the player and AIs are falling through it.

: '''Problem:''' On GridIgnore-flagged uneven ground, AIs can fall through it when they are out of the player's view.
: '''Solution:''' Use either '''chr_lock_active ''AI_name''''' or '''chr_all_active = 1'''

====Debugging====
'''(OniSplit v0.9.93.0+)'''
[[Image:OniBrowser.jpg|thumb|200px|right|OniBrowser displaying level geometry plus PF and ghosts.]]

* '''env_show_ghostgqs = 1''' makes the ghost quads visible
** The original ghost quads can't be seen; per Neo, "they are not included in the octtree and bsp tree"
** To see them you must use the -debug option in the level creation command (available with OniSplit '''v0.9.93.0+''')
OniSplit.exe -create:level ''output_folder'' '''-debug''' ''input_folder''/''master_xml_file''.xml

Not all debugging/testing needs to be done in Oni. There is also a [http://mods.oni2.net/node/256 program] (Windows only) which can display the whole level.

For example you can load an AKEV*.oni, select the level name, and use the hotkeys [B] and [P] to display BNVs and ghosts.

'''Bug prevention:'''

After all testing is done, you should compile the level a last time without the -debug option.

AIs appear to have trouble shooting through ghost quads that got registered in the octtree/BSP tree as seen here (<nowiki>https://www.youtube.com/watch?v=-ZugVBgBVKc</nowiki>, dead link).

====When OniSplit fails to connect PF quads====
[[Image:Pathfinding_creation__merge_polygons_to_fix_connections.jpg|thumb|200px|right|Fixed PF in compound level after underground construction...]]
It can help to merge polygons to one object and merge their edges. These become white. (Outer edges are blue.)

===<Textures>===
====...used for exceptions====
The [[#textures_tag|textures tag]] is mandatory.

AKEV textures will be imported by the master XML file automatically; you don't need to add them to that file.

: With OniSplit v0.9.82-93.0, the textures' formats will be DXT1 and (for transparent ones) BGRA4444.
: With OniSplit v0.9.94.0+ the textures' formats will be BGR and (for transparent ones) RGBA.

To change the default texture import format, use the Texture'''s''' tag. (Possible with OniSplit v0.9.94.0+.)

To change the format/flag/gunk flag of a specific texture, use the Texture tag.

An example:

<Textures Format="BGR" AlphaFormat="RGBA" MaxSize="512">
<Texture Name="GOO">
<Flags>TwoSided</Flags>
<Format>BGRA4444</Format>
<GunkFlags>NoCollision</GunkFlags>
<Image>env/images/GOO.tga</Image>
</Texture>
</Textures>

* Use the gunk flag "TwoSided" to make surfaces visible from both sides.
* If the texture comes with the gunk flag "NoCollision" then all objects with that texture will have no collision. Characters would fall through it.

Transparency and no collision together would make sense for a water-like substance. The Vago Biotech level uses this approach for the area with green toxic waste.

[[Image:making_a_surface_transparent_and_twosided.png|thumb|200px|right|'''Figure 1''']]

[[Image:AKEV_single_object_multiple_textures.png|thumb|200px|right|'''Figure 2''' one object with multiple textures, one per polygon cluster]]
[[Image:AKEV_single_object_multiple_textures_ingame.png|thumb|200px|right|'''Figure 3''' blue: two-sided glass: two-sided and transparent random metal: no flag (one-sided)]]

'''TwoSided and transparent objects'''

It's also possible to set this in Mod Tool. For TwoSided-ness, use one image source for diffuse and transparency. (It won't work with two image sources even if both sources use the same image.)

For transparency you must additionally use the three checkboxes:
* Transparency: Enable
* Transparency: Use Alpha
* Transparency: Invert

See '''Figure 1'''.

====Regular textures====
OniSplit automatically imports textures of objects in the [[#<Model>|<Model> section]]. Those objects could be considered as AKEV core geometry.

'''One texture per object'''

Furniture and Physics objects are allowed to have only one texture per object. AKEV core geometry can have one texture or multiple textures – that's up to you to decide.

'''Multiple textures per object'''

'''Question:''' How do we apply multiple textures to an AKEV core object?

'''Answer:''' Assuming you are using Mod Tool the procedure will be as follows. Repeat this for each cluster you create (except for projection). See also '''Figure 2 and 3'''.

* Select some polygons
* Go to Material > Phong
* Hit [7] to open Render Tree
* Add a texture and connect "Image" with "Phong", choose "diffuse" as illumination mode
* Double-click "Image" to open Material page
* In the Texture Projection section, click on "New" and choose a suitable projection
** Do this only if there isn't a projection in the "Texture_Coordinates_AUTO" cluster yet
** OniSplit processes only one texture projection, see '''Figure 4'''
* Choose the texture and UV, then fine-tune the UV via Alt + 7

[[Image:AKEV_multiple_textures_one_projection.png|thumb|200px|right|'''Figure 4''' use only one texture projection per object]]

Caution: textures will be fixed to one set of flags. You can't use the same texture A for a one-sided cluster/object B and a two-sided cluster/object C. You would need to create a differently-named clone of that texture and apply that to cluster/object C.

====Marker textures====
Marker textures are used to import certain objects with special flags. Import those objects alongside [[#<Model>|AKEV core]] geometry.

Marker textures aren't imported automatically. Add those textures to the final package or plugin yourself, e.g. with some sort of script.

OniSplit.exe -create:txmp out env/markers/*.tga

The flags Transparent, TwoSided and NoOcclusion are only set if the same texture source is used for diffuse and transparency and if transparency setting are enabled. See the subsection under "[[#...used for exceptions|...used for exceptions]]" called "TwoSided and transparent objects".

'''Danger quads'''

Pathfinding grids have different colored squares with different meanings.
* white/gray - clear space
* green light - near wall
* green - semi-passable
* green dark - stairs
* blue very light - border 1
* blue light - border 2
* blue - border 3
* blue dark - border 4
* '''orange - danger'''
* red - impassable

For detailed information on colors, see [[OBD_talk:AKVA/0x24#EFFECTS_of_various_pathfinding_grid_tile_types|HERE]].

Normally, OniSplit decide how to color the grids. But it's possible to add your own danger quads to fine-tune zones of higher danger. Those orange areas will be generated with the 4 different blue borders around it.

Danger quads must have "'''_marker_danger'''" as texture name.

Results in flags: Transparent TwoSided NoCollision Invisible NoOcclusion Danger

'''_marker_barrier'''


Results in flags: Transparent TwoSided(double-check) Invisible NoObjectCollision NoOcclusion

'''COLLISION (boxes)'''

AIs can get stuck in detailed geometry. This can be prevented with collision boxes. In-game the box will be invisible, but has collision so characters can't get through. The pathfinding grid will be red where it comes in contact with the box; the red is followed by a light green and then regular green.

[[XML:OFGA|OFGAs]] use the COLLISION texture. Onisplit doesn't automatically apply gunk flags to it. You need to use XML tags for that. Typically it would be <GunkFlags>Invisible NoObjectCollision</GunkFlags>

'''Stairs'''

Texture: '''_marker_stairs'''

Normally, characters can't move on stairs because they contain vertical rises. In this case you can use a sloping quad that is above or inside the staircases. It's possible to set the desired flags in the <Model> section, but doing so and exporting these self-made stair ramps is wasted time. Simply apply _marker_stairs to that quad and characters will be able to move on that surface.

Resulting flags: Stairs Transparent TwoSided Invisible NoObjectCollision NoOcclusion

This has no effect on pathfinding creation. Regularly-textured stair geometry (which intersects the marker quad) will be flagged as NoCharacterCollision.

'''Impassable'''

texture: '''_marker_impassable'''

Resulting flags: Transparent TwoSided (<-double-check this) Invisible NoOcclusion

Impassable walls are very similar to collision boxes except that particles can also collide with them. The pathfinding grids will be also red, light green, and green.

'''Blackness a.k.a. jello fix'''

Texture: '''_marker_blackness'''

Resulting flags: TwoSided NoCollision

Simply black walls. No effect on pathfinding creation. The purpose of these walls in Oni is to block out areas outside of a level's outermost wall so that the Jello-cam cannot show the player other parts of the level when it escapes a wall. See [[Jello-cam]] for details.

'''Doors'''

Texture: '''_marker_door'''

Resulting flags: DoorFrame Transparent TwoSided NoCollision NoOcclusion

Don't use this.

===<Objects>===
Information on regular object lists can be looked up here:
: [[XML:BINA/OBJC/CHAR|Character.xml]] (has to contain player character if there's no AISA file with it)
: [[XML:BINA/OBJC/CONS|Console.xml]]
: [[XML:BINA/OBJC/DOOR|Door.xml]]
: [[XML:BINA/OBJC/FLAG|Flag.xml]]
: [[XML:BINA/OBJC/NEUT|Neutral.xml]]
: [[XML:BINA/OBJC/PART|Particle.xml]]
: [[XML:BINA/OBJC/PATR|PatrolPath.xml]]
: [[XML:BINA/OBJC/PWRU|PowerUp.xml]]
: [[XML:SNDD#BINACJBOSound.xml|Sound.xml]]
: [[XML:BINA/OBJC/TRIG|Trigger.xml]]
: [[XML:BINA/OBJC/TRGV|TriggerVolume.xml]]
: [[XML:BINA/OBJC/WEAP|Weapon.xml]]

====Furniture.xml====
The AKEV core geometry is more or less the overall structure of the level while this furniture file adds standard objects (e.g. crates and desks) to it.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Objects>
| -
| This tag marks the file as BINACJBO.
|-
| <Furniture>
| -
| This tag marks the file as FURN.
|-
| <Header>
|
|
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag. Ignore it. Those flags were used in the past.
:None
:Locked
:PlacedInGame
:Temporary
:Gunk
|-
| <Position>
| float x3
| Optional tag. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag. X Y Z rotation.
|-
| <OSD>
| -
|
|-
|valign="top"| <Class>
|valign="top"| link
| File path to a '''pre-compiled [[XML:OFGA|OFGA]] (*.oni) file'''. Use it as part of a relative path. Make sure that the OFGA comes with the files it needs: M3GM and TXMP.

An OFGA can hold multiple M3GMs. That 3D content will then be integrated into the AKEV.
|-
|valign="top"| <Particle>
|valign="top"| string
| This name gets written into <Tag> inside ONLV (ENVP section) and can be used with BSL commands, e.g. you can take control over a particle via '''particle BSL_name start'''. For more commands, see [[XML:BINA/OBJC/PART#BSL_support|HERE]].

Take care with the naming of new OFGA files. The particle name will be composed of 2 parts separated by an "_" underscore. When one tag is empty, the final name will contain an underscore nonetheless. '''Examples:'''

: FURN <Particle>test</Particle> + OFGA <Tag>streetlight</Tag> = '''test_streetlight'''
: FURN <Particle></Particle> + OFGA <Tag>streetlight</Tag> = '''_streetlight'''
: FURN <Particle>test</Particle> + OFGA <Tag></Tag> = '''test_'''
|}

;Example

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Objects>
[...]
<Furniture>
<Header>
<Flags>Gunk</Flags>
<Position>-62.692 -29 108.35</Position>
<Rotation>181.522 356.021 178.114</Rotation>
</Header>
<OSD>
<Class>furniture/V_tctf_bigvan.oni</Class>
<Particle></Particle>
</OSD>
</Furniture>
[...]
</Objects>
</Oni>

====Physics.xml====
This file is for objects with "physics". Unlike AKEV core geometry or furniture, these objects can be animated.

: A small video tutorial on [https://www.youtube.com/watch?v=CFNseg_2UxA how to create a simple animated object]

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Physics>
| -
|
|-
| <Object Name="...">
| string
| Use a unique name for each object.
|-
|valign="top"| <ScriptId>
|valign="top"| integer
| Tested with BSL command...
:obj_create ID [ID]
:obj_kill ID [ID]
:env_anim ID [ID]
:env_setanim ID [ID]
The scripting ID will be stored in the ONLV's OBOA instance.
|-
|valign="top"| <Flags>
|valign="top"| flag
|
;Object setup flags
:None
:InUse
:NoCollision
:NoGravity
:FaceCollision
|-
|valign="top"| <Physics>
|valign="top"| flag
| Optional tag for an Object.
:None
:Static
:Linear
:Animated
:Newton (used with <Flags> FaceCollision to [https://www.youtube.com/watch?v=YICB7qugrtc make an object pushable])
:: For a pushable object don't use import sub-tags such as animation name, flags, etc. Just use <Import Path="..." '''/'''> or <Import Url="..." '''/'''>
|-
| <Position>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z position.
|-
| <Rotation>
| float x3
| Optional tag of Object. Only used for non-animated objects. X Y Z rotation.
|-
| <Scale>
| float
| Optional tag of Object. Only used for non-animated objects.
|-
|
<Import Path="...">

<Import Url="...">
|valign="top"| link
|valign="top"| This tag comes in two variants. It doesn't matter what variant you use.
|-
| <Animation Name="...">
| link
| File path to *.dae file.
|-
|valign="top"| <Flags>
|valign="top"| flag
| Optional tag of Animation. For more information on those flags look [[XML:OBAN|OBAN]] page.

;Object animation flags
:None
:Loop
:PingPong
:RandomStart
:AutoStart
:Local
|-
| <End>
| integer
| Optional tag of Animation. Frame number. Used to define the end of an OBAN from a *.dae file.
|-
| <Start>
| integer
| Optional tag of Animation. Frame number. Used to define the start of an OBAN from a *.dae file.
|}

The XML code for physics can be written in two styles.
*The '''first style''' mimics the original structure found in extracted ONLV instances. This makes it '''easier to edit old levels and reimport them''' into the game.
*The '''second style''' was created with structured data (nested objects) in mind and is '''suited for totally new levels''' where animated objects must be created in a 3D editor at first.

'''Code style 1'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
<Object>
<Geometry>M3GMDishBase.oni</Geometry>
<Animation>OBANDishBase.oni</Animation>
<Physics>Animated</Physics>
<ScriptId>201</ScriptId>
<Position>-197.729141 128.46283 -2501.46387</Position>
<Rotation>0.7071067 -1.545431E-08 1.545431E-08 0.7071068</Rotation>
<Scale>2.109375</Scale>
<Name>object_DishBase</Name>
</Object>
</Physics>
</Oni>

'''Code style 2'''
:For documentation purposes, the file here has been trimmed down.

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Physics>
[...]
<Object Name="motorcycle">
<ScriptId>8</ScriptId>
<Flags>FaceCollision</Flags>
<Import Url="motorcycle/export.dae">
<Animation Name="motorcycle02">
<Flags>AutoStart</Flags>
<End>880</End>
</Animation>
<Animation Name="motorcycle02_stop">
<Start>881</Start>
</Animation>
</Import>
</Object>
[...]
</Physics>
</Oni>

In this example, OniSplit takes the file "export.dae", looks at the parts it contains, and creates geometry files from it.
* M3GMhubs_rear.oni
* M3GMhubs.oni
* M3GMmotorcycle.oni
It's convenient that hierarchies are supported here.

The motorcycle is made of 3 parts so 3 object animations ([[XML:OBAN|OBAN]]) will be created up to frame 880. Then OniSplit creates 3 more OBANs starting from frame 881.

The reason for the interruption at frame 880 is probably to give Barabas a little more camera time in the cutscene.

;Notes about BSL usage:

The Vago Lab cutscene script uses the motorcycle objects and animations like this:
env_show 8 0 # hide static motorcycle parts or else they would be visible
env_show 9 0 # while Konoko is still riding her animated motorcycle
env_show 10 0 # the static motorcycle is separated into objects 8, 9 and 10

# Static and animated objects are totally independent from each other.
# They are stored in different arrays so their script IDs can use the same numbers.

obj_create 8 10 # create all animation-ready motorcycle parts
env_anim 8 10 # animate those parts (not necessary if OBAN flag is "AutoStart")

# The first animations would loop because of "AutoStart", so get the
# right timing to apply the other animations. "motorcycle02_stop"
# and the others will not loop because they don't have "AutoStart".
env_setanim 8 hubs_stop
env_setanim 9 hubs_rear_stop
env_setanim 10 motorcycle02_stop

obj_kill 8 10 # delete all animated parts
env_show 9 1 # show static motorcycle model where Konoko parks her bike

====Corpses.xml====
An empty Corpse element (<Corpse />) is treated as unused and placed at the end of the array. If no such empty elements are provided, OniSplit automatically adds 5. OniSplit also ensures that there are at least 20 corpses in the array.

{| class="wikitable" width="100%"
!width=150px| XML tag
!width=120px| Content type
! Description
|-
| <Corpses>
|
|
|-
|valign="top"| <Corpse>
|valign="top"| -
|
|-
| <Class>
| link
| [[XML:ONCC|ONCC]]''name''
|-
| <Transforms>
| -
| There are 19 <Matrix> for each <Transforms> (which represents a body part).
|-
| <Matrix>
| matrix
| Float 3x3 + float x3 for the last 3 values (X Y Z position). For more information about the matrix, see [[OBD:CRSA]].
|-
| <BoundingBox>
| -
| Bounding box of the whole corpse. Optional; if not provided, OniSplit will generate an approximate one. Currently it doesn't try to locate the ONCC to compute an exact bounding box.
|-
| <Min>
| float x3
|
|-
| <Max>
| float x3
|
|}

'''Trimmed example'''

<?xml version="1.0" encoding="utf-8"?>
<Oni>
<Corpses>
<Corpse>
<Class>generic_male_1</Class>
<Transforms>
<Matrix>-0.36488995 0.04620622 -0.9299034 -0.05580434 -0.9980576 -0.02769538 -0.9293768 0.04178688 0.366759717 -215.667755 1.603917 92.85312</Matrix>
<Matrix>0.2961557 -0.185628444 0.936928 -0.368288517 -0.9272724 -0.06730227 0.8812806 -0.32512787 -0.342981815 -216.51889 1.64218426 93.189</Matrix>
<Matrix>0.407847315 0.156575248 0.8995248 -0.238757968 -0.9326179 0.2705892 0.8812805 -0.3251278 -0.342982143 -215.239883 0.8405094 97.23532</Matrix>
<Matrix>0.439697325 0.467113584 0.767118752 0.0248355754 -0.8601105 0.5095029 0.8978026 -0.204975232 -0.389789373 -213.6234 1.46109009 100.80056</Matrix>
<Matrix>0.717241049 -0.179043233 0.673430443 0.4761817 -0.579636 -0.6612664 0.5087397 0.794962764 -0.3304816 -214.81662 1.56564879 92.5172348</Matrix>
<Matrix>0.3398023 0.1672905 0.925498843 0.7910236 -0.5831365 -0.185023025 0.5087395 0.7949628 -0.330481827 -211.71907 0.792413354 95.42558</Matrix>
<Matrix>0.1283634 0.227430075 0.965297 0.804142356 -0.59352535 0.032904774 0.5804117 0.7720126 -0.259073079 -210.372269 1.45546341 99.0937653</Matrix>
<Matrix>-0.285799921 0.06851995 -0.955836535 -0.240357026 -0.970681965 0.00228381017 -0.927656651 0.230394751 0.2938901 -216.284851 1.5839076 91.29168</Matrix>
<Matrix>-0.312039882 0.04875436 -0.948817253 -0.176752359 -0.9842264 0.00755515043 -0.9334825 0.1700632 0.31573534 -216.689789 1.68287766 89.9359055</Matrix>
<Matrix>-0.356412441 -0.5390179 -0.763170958 0.0404523835 -0.82494843 0.5637587 -0.933452547 0.170058519 0.315826446 -217.422012 1.7979821 87.70907</Matrix>
<Matrix>-0.101782769 -0.247171819 -0.9636112 0.5426916 -0.8256094 0.154451028 -0.8337422 -0.507223248 0.2181709 -217.747284 1.30605173 87.0125656</Matrix>
<Matrix>-0.8154478 -0.150626346 0.558888733 -0.1200991 0.9885643 0.09119747 -0.566234052 0.00724477554 -0.8242127 -217.7402 2.065678 88.15346</Matrix>
<Matrix>-0.4593738 -0.326781839 0.825947642 0.8874048 -0.1284554 0.442732215 -0.0385793857 0.9363295 0.348996729 -219.093979 1.81561315 89.08131</Matrix>
<Matrix>-0.9545983 -0.13777709 0.26412034 0.295387268 -0.322961926 0.899134 -0.0385792255 0.9363296 0.348996431 -220.3681 0.9092429 91.37218</Matrix>
<Matrix>-0.9715769 -0.0362956524 0.233924776 0.0276728421 -0.9988148 -0.0400396362 0.2351007 -0.0324283168 0.9714299 -222.775482 0.56178683 92.03825</Matrix>
<Matrix>0.979860842 -0.192433611 0.0533096045 0.193336874 0.9810555 -0.0122905634 -0.0499345176 0.0223497637 0.9985025 -216.8387 1.90143847 87.84845</Matrix>
<Matrix>0.863898 -0.399280578 0.3070101 0.171117 -0.340619326 -0.9244986 0.4737078 0.851207137 -0.225936681 -215.211975 1.58196676 87.93695</Matrix>
<Matrix>0.4673251 -0.0255063027 0.883717656 0.746463835 -0.524209559 -0.4098731 0.4737075 0.851207256 -0.225936785 -212.815842 0.47451216 88.78848</Matrix>
<Matrix>0.216871262 -0.007893051 0.976168454 0.3751846 0.9238389 -0.0758833 -0.9012231 0.3827002 0.203315422 -211.637314 0.410188764 91.0171051</Matrix>
</Transforms>
<BoundingBox>
<Min>-219.731216 -2.258905 84.47974</Min>
<Max>-207.518463 4.49535131 104.023239</Max>
</BoundingBox>
</Corpse>
</Corpses>
</Oni>





[[Category:Modding tutorials]]