OniSplit: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (effect of -noanim)
(37 intermediate revisions by 5 users not shown)
Line 1: Line 1:
'''OniSplit''', written by [[User_talk:Neo|Neo]], is an integral part of the [[Anniversary Edition]] and an essential modding tool on its own. It does the work of splitting and recombining Oni's data files. But it also does much more, such as extracting and creating textures, 3D and .xml files.
{{TOCfloat|side=right}}
:''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.


==Getting it==
==Getting it==
===Download links===
===Download links===
* Latest version of OniSplit: [http://mods.oni2.net/sites/default/files/OniSplit.exe_.zip v0.9.40]
* Latest release of OniSplit: [http://mods.oni2.net/node/38 v0.9.99.0]
* Latest version of OniSplit GUI can be found [http://oni.bungie.org/community/forum/viewtopic.php?pid=9323#p9323 here.]
* 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===
===Requirements===
OniSplit requires .NET 2.0 for Windows and the Mono framework for Mac OS X.
OniSplit requires .NET 2.0 in Windows and the Mono framework in macOS.
 
* [http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en .NET 2.0]
* [http://www.go-mono.com/mono-downloads/download.html Latest version of mono (requires OS X 10.4+)]
* [http://edt.oni2.net/AE/MonoFramework10.3.dmg Mono for OS X 10.3]
 


----
* [http://download.microsoft.com/download/c/6/e/c6e88215-0178-4c6c-b5f3-158ff77b1f38/NetFx20SP2_x86.exe .NET 2.0 (x86)]; [http://download.microsoft.com/download/c/6/e/c6e88215-0178-4c6c-b5f3-158ff77b1f38/NetFx20SP2_x64.exe .NET 2.0 (x64)]
* [http://www.go-mono.com/mono-downloads/download.html Latest version of mono]


==Using it==
==Workflow==
The following actions are listed when calling OniSplit with the <tt>-help</tt> option (another informative option is <tt>-version</tt>)
OniSplit is used in up to four different stages when modding:
:The command line must be preceded by either <tt>OniSplit.exe</tt> (Windows) or <tt>mono OniSplit.exe</tt> (Mac OS)
::If OniSplit.exe is not in the current folder, you can provide the full/relative path to it or set the path variable.
:::On the Mac, be sure to use / rather than \ in paths. The following instructions are for Windows by default.
====Conversion between .dat and .oni====
{|
{|
|<tt>-export <target directory> <source file></tt>||Exports source file (.dat) to target directory
|rowspan="2"|<span style="font-size:150%">'''OUT'''</span>
|''Exporting'' - using the <tt>-export</tt> command, a [[Dat|level data file]] is broken into its component resources, .oni files.
|-
|-
|<tt>-import <source directory> <target file></tt>||Imports target file (.dat) from source directory; tries to get target file format from source SNDD
|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.
|-
|-
|<tt>-import:sep <source directory> <target file></tt>||Imports target file (.dat) from source directory; uses .dat+.raw+.sep format (Mac and PC Demo)
|rowspan="2"|<center><span style="font-size:150%">'''IN'''</span></center>
|''Creating'' - using the <tt>-create</tt> commands, standard-format files are converted into .oni files.
|-
|-
|<tt>-import:nosep <source directory> <target file></tt>||Imports target file (.dat) from source directory; uses .dat+.raw format (PC retail)
|''Importing'' - using the <tt>-import</tt> command, a folder of .oni files is combined into a level data file.
|}
|}
:Note that -import 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 anyway you like. The only exception is that a subdirectory named "noimport" or "_noimport" is always ignored.


====Management of .oni files====
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).
Unless mentioned otherwise, the filename field supports wildcards ("*").
 
:OniSplit consistently detects and manages "dependencies" of .oni files.
==Beginner's tips==
::The dependencies of a file are looked up in its folder and subfolders.
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
In Windows, you want to find the Command Prompt. The fastest way to get there is to bring up the "Run..." dialog with Windows+R, then type "cmd" and hit Enter.
 
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:
{|
{|
|<tt>-deps <filenames></tt>||Displays a list of .oni files that the specified .oni file depends on
|-
|-
|<tt>-copy <target directory> <filenames></tt>||Copies .oni file and its dependencies to target; skips file if it already exists at destination
|'''Windows'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">OniSplit.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">-create:trbs</span> <span style="background:rgb(255,156,156); border-radius:0.33em;">C:\Games\Oni\SomeFolder</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">-normals</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">C:\Games\Oni\Modding\TRBSMyNewChar.dae</span></tt>
|-
|-
|<tt>-move <target directory> <filenames></tt>||Moves an .oni file and its dependencies to target; skips file if it already exists at destination
|'''Mac'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em;">mono OniSplit.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">-create:trbs</span> <span style="background:rgb(255,156,156); border-radius:0.33em;">/Games/Oni/SomeFolder</span> <span style="background:rgb(175,175,255); border-radius:0.33em;">-normals</span> <span style="background:rgb(156,255,156); border-radius:0.33em;">/Games/Oni/Modding/TRBSMyNewChar.dae</span></tt>
|}
 
Here's how it breaks down:
{|
! style="width:130px"|
|- valign="top"
|<span style="background:rgb(235,235,235); border-radius:0.33em;">'''Invocation'''</span>
|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.
|-
|-
|<tt>-move:overwrite <target directory> <filenames></tt>||Moves an .oni file and its dependencies to target; overwrites any existing .oni files
|<span style="background:rgb(175,175,255); border-radius:0.33em;">'''Option'''</span>||The command.
|- valign="top"
|<span style="background:rgb(255,156,156); border-radius:0.33em;">'''Path to folder'''</span>||Whether destination or source, the path which is a folder comes first. <u>Use the full path to the folder (starting from "C:\", or "/" on Macs).</u>
|-
|-
|<tt>-move:delete <target directory> <filenames></tt>||Moves an .oni file and its dependencies to target; doesn't overwrite; deletes source files
|<span style="background:rgb(175,175,255); border-radius:0.33em;">'''Option flags'''</span>||The flags that can optionally go with this command, separated by spaces.
|- valign="top"
|<span style="background:rgb(156,255,156); border-radius:0.33em;">'''Path to file'''</span>||Whether destination or source, the path of the file comes second. <u>Use the full path to the file (starting from "C:\", or "/" on Macs).</u> 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.
|}
|}
====Conversion between .oni/.dat and 3rd party formats====
 
=====Textures=====
===CLI tips===
Unless mentioned otherwise, source filenames support wildcards. See [[AE:Modifying textures|HERE]] for a detailed tutorial.
*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:Oni username$''' 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===
{|
{|
|<tt>-extract:dds <target directory> <filenames></tt>||Extracts all textures (TXMP) from a Oni .dat/.oni file in DDS format
! style="width:430px"|
|-
|<code>-list <file name></code>||Lists the named resources contained in a .dat (see [[OBD:File_types/Named|HERE]] for info on unnamed resources)
|-
|<code>-export <destination directory> <dat file></code>||Breaks .dat file into .oni files
|-
|<code>-export:<pattern> <destination directory> <dat file></code>||Exports named resource (wildcards also allowed) from .dat file
|- valign="top"
|<code>-import <source directory> <new dat file></code>||Compiles level files from source directory using the name you supply for the .dat file; tries to get target file format from source SNDD, but it's better to use the :sep or :nosep variants below
|-
|-
|<tt>-extract:tga <target directory> <filenames></tt>||Extracts all textures (TXMP) from a Oni .dat/.oni file in TGA format
|colspan="2"|<span style="padding-left:20px">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><span>
|-
|-
|<tt>-extract:png <target directory> <filenames></tt>||Extracts all textures (TXMP) from a Oni .dat/.oni file in PNG format
|<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)
|-
|-
|align=right|<tt>-create:txmp <targer directory> [-genmipmaps] [-nouwrap] [-novwrap]<br><nowiki>[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]</nowiki><br>[-envmap:texture_name] <filename></tt>
|<code>-import:nosep <source directory> <new dat file></code>||Imports target file (.dat) from source directory; uses .dat/.raw format (PC retail)
|valign=top|Creates .oni file in target directory from source image
|}
|}
The -extract commands can work with .oni files (a single file or several files, wildcards possible) or rip all the TXMPs from a .dat file.
: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.


=====Models=====
===Management of .oni files===
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can be exported to the Wavefront .obj and COLLADA .dae formats. For details see [[AE:Importing character models|HERE]] and [[AE:Importing weapon models|HERE]]
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.
{|
{|
|<tt>-extract:obj <target directory> <filenames></tt>||Extracts all M3GM, ONWC and ONCC instances to Wavefront OBJ files
|<code>-deps <oni file></code>||Displays a list of .oni files that the specified .oni file depends on
|-
|-
|<tt>-extract:dae <target directory> <filenames></tt>||Extracts all M3GM, ONWC and ONCC instances to Collada files
|<code>-copy <destination directory> <oni file></code>||Copies .oni file and its dependencies; skips file if it already exists at destination
|-
|-
|<tt>-create:m3gm <target directory> [-tex:texture_name] <filename></tt>||Creates a TRBS .oni in target directory from an .obj file
|<code>-move <destination directory> <oni file></code>||Moves an .oni file and its dependencies; skips file if it already exists at destination
|-
|-
|<tt>-create:trbs <target directory> [-cel] [-normals] <filename></tt>||Creates a TRBS .oni in target directory from a .dae file
|<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
|}
|}
The generic -extract commands can work with .oni files (a single file or several files, wildcards possible) or rip all the TXMP from a .dat file.
:TRBS and ONCC support additional -noanim and -anim options for -extract:dae, see [[AE:Importing character models|HERE]] for details.
::Imported geometry must only contain triangles. See [[AE:Importing character models|HERE]] for additional options (e.g., cel-shading)
====Levels====
OniSplit can convert AKEV files (level geometry) and the associated file types to and from DAE format:


<tt>-extract:dae <target directory> <name of AKEV.oni source file></tt>  Extracts all AKEV and related instances to Collada files
===Conversion between .oni/.dat and 3rd party formats===
 
====Textures====
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.  
Unless mentioned otherwise, source filenames support wildcards. See [[AE: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.
 
<tt>-create <target directory> -genmipmaps -format:dxt1 <source directory/>*.xml</tt>   Converts all AKEV and related instances to .oni files
 
<tt>-import:nosep <source directory> <target file name>.dat</tt>  The standard command for creating .dat/.raw files from .oni files (remember to use the import:sep option on Mac!)
 
=====Misc=====
Some more import/export functions, e.g., to rip sounds or rip/replace subtitles.
{|
{|
|<tt>-extract:wav <target directory> <filenames></tt>||Rips all SNDD as .aif into target folder from source .dat or .oni
|<code>-extract:dds <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into DDS files
|-
|-
|<tt>-extract:aif <target directory> <filenames></tt>||Rips all SNDD as .aif into target folder from source .dat or .oni
|<code>-extract:tga <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into TGA files
|-
|-
|<tt>-extract:txt <target directory> <filenames></tt>||Rips all SUBT as .txt into target folder from source .dat or .oni
|<code>-extract:png <destination directory> <dat/oni file></code>||Extracts all textures (TXMP) from a Oni .dat/.oni file into PNG files
|-
|-
|<tt>-create:subt <target directory> <filename></tt>||Creates a SUBT .oni file in target folder from a .txt file
|<code>-create:txmp <destination directory><br>[-genmipmaps] [-nouwrap] [-novwrap]<br><nowiki>[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]</nowiki><br>[-envmap:texture_name] <image file></code>
|valign=top|Creates .oni file from image file (PNG, TGA, or DDS)
|}
|}
=====XML=====
 
One of the latest features is conversion of an .oni file (binary) into an XML metafile and back. XML files are more explicit and more readily editable.
====Models====
::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]].
[[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.
:::For detailed examples and tutorials, see [[AE:XML|HERE]]
{|
{|
|<tt>-extract:xml <target directory> <filenames></tt>||Extracts all instances to XML files
! 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
|-
|-
|<tt>-create <target directory> <filename></tt>||Creates an .oni file in the target directory from an XML file
|<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
|}
|}


BIG NOTE OF WARNING: some of the above instance types (most importantly ONWC) contain geometry data (M3GM) embedded in them. The geometry can round-trip through xml but versions of OniSplit up to and including 0.9.26 produce an invalid .oni file that may cause Oni to crash.
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.
[[Category:Modding tools]][[Category:Articles that need updating]]


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


==Change Log==


New OniSplit version: OniSplit v0.9.40
The next two steps are used on a folder in which you have placed the DAE and XML-formatted instances of the required files, as well as textures in TGA format. See [http://oni.bungie.org/community/forum/viewtopic.php?id=1515 HERE] for details.
{|
|- valign="top"
|<code>-create <destination directory><br>[-genmipmaps] [-format:dxt1]<br><source directory></code>||Converts all AKEV and related instances to .oni files
|- valign="top"
|<code>-import:nosep <source directory><br><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!)
|}


What's new:
====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
|}


:* support for exporting/importing [[OBD:BINA/SABD|sound animations]] to/from xml files
====Text====
:* better Collada export for environment
{|
:* support for full color transparent textures (-format:bgra32 on the command line, ARGB8888 format in an xml file)
|<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
:* different (hopefully better) xml export format for animations (this one is actually from 0.9.38 but since that wasn't mentioned here...)
|-
:* a more or less complete animation importer. This one deservers some notes:
|<code>-create:subt <destination directory> <TXT file></code>||Creates a SUBT .oni file from a .txt file
::-unlike other importers that produce .oni files this one produces and .xml file (similar to the one you get when exporting a TRAM)
|}
::when you do
  onisplit -create:tram target_dir animation.dae
::in the target dir you'll get a TRAManimation.xml file.
::You need to add some stuff to that file to make it actually work as an animation. In particular the animation type, from/to states and varient needs to be set.
::-For all I know this works with animations exported from Oni and modified in Softimage. If you come up with a completly new animation it should work as long as the skeleton is similar to the one used in Oni.
::-Note that the geometry that is present inside the Collada file is used to compute the "vertical extents" so it better be the same or close to the one the animation is intended for.
::-The biggest problem are the attacks. While it's not difficult to add attacks to the xml file, computing the necessary "extents" is not going to be easy. I guess in the end I'll have to add some command to OniSplit to do it.
::-Everything else that I forgot :)


[[User:Neo|Neo]]
====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.
New OniSplit version: [http://cid-639aa31296681bfe.skydrive.live.com/self.aspx/Oni/OniSplit/OniSplit|_v0.9.37.zip OniSplit v0.9.37]
::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]]
What's new:
{|
 
|<code>-extract:xml <destination directory> <oni file></code>||Extracts .oni file and all related resources to XML files and 3rd-party formats
:* support for transparency in the environment importer
|-
 
|<code>-create <destination directory> <XML file></code>||Creates an .oni file from an XML file
 
|}
New OniSplit version: OniSplit v0.9.35
 
What's new:
 
:* conversion of recorded films (.dat binary files) to xml files that can be used to create FILM .oni files
 
    OniSplit film2xml out_dir film.dat
 
 
New OniSplit version: OniSplit v0.9.34
 
What's new:
 
:* SNDD importer
::-WAV files (.wav, mono/stereo, 22.05KHz/44.1KHz, uncompressed(PCM)/compressed(MS-ADPCM)) produce SNDD files that are compatible with Oni PC retail.
::-AIFC files (.aif/.aifc/.afc, mono/stereo 22.05KHz, compressed(ima4)) produce SNDD files that are compatible with Oni Mac.
::Example
 
 
 
  OniSplit -create out_dir test.aif
  OniSplit -create out_dir test.wav
 
 
:*LOD support for creating TRBS files. This can be done by creating an xml file containing the following:
 
  <?xml version="1.0" encoding="utf-8"?>
  <Oni Version="0.9.29.0">
      <Instance id="0" type="TRBS">
          <Elements>
              <Link>barabus_body_1.dae</Link>
              <Link>barabus_body_2.dae</Link>
              <Link>barabus_body_3.dae</Link>
              <Link>barabus_body_4.dae</Link>
              <Link>barabus_body_5.dae</Link>
          </Elements>
      </Instance>
  </Oni>
 
::and running the command (assuming the created xml file's name is barabus_body.xml):
 
  OniSplit -create out_dir barabus_body.xml
 
::It's not strictly necessary to create 5 different geometries for each LOD. The following works just as well:
 
  <?xml version="1.0" encoding="utf-8"?>
  <Oni Version="0.9.29.0">
      <Instance id="0" type="TRBS">
          <Elements>
              <Link>barabus_body_1.dae</Link>
              <Link>barabus_body_2.dae</Link>
              <Link>barabus_body_2.dae</Link>
              <Link>barabus_body_2.dae</Link>
              <Link>barabus_body_3.dae</Link>
          </Elements>
      </Instance>
  </Oni>
 
 
:*An xml file can contain "links" to other xml/obj/dae files. For example you can have the following line in an ONWC xml file:
 
  <Geometry>pistol.obj</Geometry>
 
::Assuming the file pistol.obj exists in the same directory an M3GM .oni file will be automatically created from it.
 
::Relative paths work just as well:
 
  <Geometry>geometry/pistol.obj</Geometry>
 
 
:*The -create:subt, -create:txmp and -create:m3gm are sort of obsolete. They still work but now you can simply use '-create' (or just 'create'):
 
  OniSplit -create out_dir crate.dae
  OniSplit create out_dir -format:bgr555 -genmipmaps pic.tga
  OniSplit create out_dir subtitles.txt
 
 
:*Work in progress: the AKEV importer now reads Collada materials so the resulting AKEV is textured.
 
:Sample levels:
:[http://cid-639aa31296681bfe.skydrive.live.com/self.aspx/Oni/noglass.zip TestLevel1] -- This level should look like this in-game: <u>[[:Image:NoGlass Import Test 1.jpg|Image 1]]</u> <u>[[:Image:NoGlass Import Test 2.jpg|Image 2]]</u> <u>[[:Image:NoGlass Import Test 3.jpg|Image 3]]</u>
:[http://cid-639aa31296681bfe.skydrive.live.com/self.aspx/Oni/hexagon.zip TestLevel2] -- This level should look like this in-game: <u>[http://edt.oni2.net/images/hexagon1.jpg Image 1]</u>
:A zip file contains the minimum needed to get a new level running in Oni. To "compile" a level extract it to a folder and run the following commands:
  OniSplit -create out -genmipmaps -format:dxt1 *.xml
  OniSplit -import:nosep . Oni\GameDataFolder\level1_Final.dat
 
:(Of course, you need to change the output .dat file path to match your Oni installation path)
 
:Note1: The hexagon level needs to be scaled up to work properly. Use the envscale option for this:
  OniSplit -create out -genmipmaps -format:dxt1 -envscale:40 *.xml


:Note2: I've updated the level files to contain 20 empty corpses to prevent crashes.
[[Category:Completed modding tools]][[Category:Bi-platform modding tools]][[Category:Modding tutorials]]

Revision as of 11:40, 28 December 2017

Before reading this page, it's a good idea to be familiar with basic Oni game data terminology.

OniSplit, written by 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 knowledge about Oni's game data, and it is currently the community's main modding tool.

Getting it

Download links

  • Latest release of OniSplit: v0.9.99.0
  • The current GUI for OniSplit is Vago. You should try the GUI to see if it does what you need before working with OniSplit on the command line.

Requirements

OniSplit requires .NET 2.0 in Windows and the Mono framework in macOS.

Workflow

OniSplit is used in up to four different stages when modding:

OUT Exporting - using the -export command, a level data file is broken into its component resources, .oni files.
Extracting - using the -extract commands, .oni files are converted to standard-format files that can be edited in various third-party programs.
IN
Creating - using the -create commands, standard-format files are converted into .oni files.
Importing - using the -import 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

Commands

Conversion between .dat and .oni

-list <file name> Lists the named resources contained in a .dat (see HERE for info on unnamed resources)
-export <destination directory> <dat file> Breaks .dat file into .oni files
-export:<pattern> <destination directory> <dat file> Exports named resource (wildcards also allowed) from .dat file
-import <source directory> <new dat file> 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
To create level5_Final.dat/.raw[/.sep] from the files in MyNewLevel\: OniSplit.exe -import C:\Oni\MyNewLevel\ C:\Oni\GameDataFolder\level5_Final.dat
-import:sep <source directory> <new dat file> Imports target file (.dat) from source directory; uses .dat/.raw/.sep format (Mac and PC Demo)
-import:nosep <source directory> <new dat file> Imports target file (.dat) from source directory; uses .dat/.raw format (PC retail)
Note that -import 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.

-deps <oni file> Displays a list of .oni files that the specified .oni file depends on
-copy <destination directory> <oni file> Copies .oni file and its dependencies; skips file if it already exists at destination
-move <destination directory> <oni file> Moves an .oni file and its dependencies; skips file if it already exists at destination
-move:overwrite <destination directory> <oni file> Moves an .oni file and its dependencies; overwrites any existing .oni files
-move:delete <destination directory> <oni file> 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 HERE for a detailed tutorial. The -extract 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.

-extract:dds <destination directory> <dat/oni file> Extracts all textures (TXMP) from a Oni .dat/.oni file into DDS files
-extract:tga <destination directory> <dat/oni file> Extracts all textures (TXMP) from a Oni .dat/.oni file into TGA files
-extract:png <destination directory> <dat/oni file> Extracts all textures (TXMP) from a Oni .dat/.oni file into PNG files
-create:txmp <destination directory>
[-genmipmaps] [-nouwrap] [-novwrap]
[-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1]
[-envmap:texture_name] <image file>
Creates .oni file from image file (PNG, TGA, or DDS)

Models

M3GMs, ONWCs, ONCCs can be exported to the Wavefront .obj and COLLADA .dae formats. For details see Importing character models and Importing weapon models. The generic -extract 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 -noanim and -anim options for -extract:dae; see Importing character models for details. Imported geometry must only contain triangles.

-extract:obj <destination directory> <dat/oni file> Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Wavefront OBJ files
-extract:dae <destination directory> [-noanim] <dat/oni file> Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Collada DAE files
-create:m3gm <destination directory> [-tex:texture_name] <OBJ file> Creates a M3GM .oni from an .obj file
-create:trbs <destination directory> [-cel] [-normals] <DAE file> 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:

-extract:dae <destination directory> <AKEV.oni file> 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 HERE for details.

-create <destination directory>
[-genmipmaps] [-format:dxt1]
<source directory>
Converts all AKEV and related instances to .oni files
-import:nosep <source directory>
<target file name>.dat
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.

-extract:wav <destination directory> <dat/oni file> Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .wav files
-extract:aif <destination directory> <dat/oni file> Rips sound data from an SNDD .oni file (or all SNDDs from a .dat) as .aif files

Text

-extract:txt <destination directory> <dat/oni file> Rips text data from a SUBT .oni file (or all SUBTs from a .dat) as .txt files
-create:subt <destination directory> <TXT file> 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 HERE
-extract:xml <destination directory> <oni file> Extracts .oni file and all related resources to XML files and 3rd-party formats
-create <destination directory> <XML file> Creates an .oni file from an XML file