OniSplit: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (→‎OniSplit commands: Fixed format)
m (link fix)
 
(86 intermediate revisions by 9 users not shown)
Line 1: Line 1:
'''OniSplit''', written by 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}}
{{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.


===Export/Import textures===
:''Subpages:'' [[/Change_log|Change log]] (past versions), [[/WIP|WIP notes]] (upcoming versions)
To export a single TXMP
  onisplit -extract:png txmp_dir ..\GameDataFolder\level0_Final\TXMPBOSS1talking.oni
To export all the [[TXMP]] files:
  onisplit -extract:png txmp_dir ..\GameDataFolder\level0_Final.dat
TGA and DDS are also supported using -extract:tga and -extract:dds.


To import image files:
==Getting it==
  onisplit -create:txmp ..\GameDataFolder\level0_Final [options] source_image_file
===Download links===
where options can be
* 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])
  -nouwrap - set the "U wrapping disabled" flag
* 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.'''
  -nowwrap - set the "V wrapping disabled" flag
 
  -format:bgr555 (or dxt1) for most of the stuff
===Requirements===
  -format:bgr32 for skyboxes
*Windows: [https://dotnet.microsoft.com/en-us/download/dotnet-framework .NET framework]
  -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)
*macOS: [https://www.mono-project.com/download/stable/ Mono framework]
  -genmipmaps - generate mipmaps if they are not already present in the source file and if the source file is not dxt1 compressed


Example:
==Workflow==
  onisplit -create:txmp ..\GameDataFolder\level0_Final -format:bgr555 -genmipmaps tga\concrete.tga
OniSplit is used in up to four different stages when modding:
To batch process a folder of image files:
{|
  onisplit -create:txmp ..\GameDataFolder\level0_Final -format:bgr555 -genmipmaps tga\*.tga
|rowspan="2"|<span style="font-size:150%">'''OUT'''</span>
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.
|''Exporting'' - using the <tt>-export</tt> command, a [[Dat|level data file]] is broken into its component resources, .oni files.
onisplit will automatically prepend TXMP to the output file name if the source file name does not start with TXMP already.
|-
|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><span style="font-size:150%">'''IN'''</span></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.
|}


For TXMP files that contain envmaps:
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).
  onisplit -create:txmp ..\GameDataFolder\level0_Final -format:bgra4444 -genmipmaps -envmap:envmapname imagefile.tga
The envmap name can have the TXMP prefix but it is added automatically if missing.


===Export/Import 3D models===
==Beginner's tips==
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can all be exported to the OBJ file format:
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
  onisplit -extract:obj dest_dir ..\GameDataFolder\level0_Final\M3GMnotfound.oni
In Windows, there are several options through which you can use OniSplit - out of which it is recommended to get Vago and CMDer:
  onisplit -extract:obj dest_dir ..\GameDataFolder\level0_Final\ONWCw1_tap.oni
* [[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.
  onisplit -extract:obj dest_dir ..\GameDataFolder\level0_Final\ONCCbarabus.oni
* [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.
Or for a total export:
* Command Prompt/cmd.exe. Windows' default command line interpreter, it's a poor choice as it does not store most recently used commands.
  onisplit -extract:obj dest_dir ..\GameDataFolder\level0_Final.dat
Importing obj files:
  onisplit -create:m3gm ..\GameDataFolder\level0_Final TCTF_Shotgun.obj
For importing obj files the obj file must only contain triangles so when exporting a model from a 3D design tool it needs to be triangulated. If the obj file uses more than one texture then only one will be taken into consideration. If the obj file does not contain a texture or someone wants to use a different one then the texture name to be used can be specified with -tex option:
  onisplit -create:m3gm ..\GameDataFolder\level0_Final -tex:TCTF_Shotgun TCTF_Shotgun.obj
Just like in -envmap option case the texture name can start with TXMP but it is not required.
Note that in both -envmap and -tex cases a .oni file is not created for the specified texture. The .oni file for that texture must be create separately.


'''For TRBS files'''


To export an ONCC or TRBS file to Collada format:
On Macs, the command line is found in the Terminal app (/Applications/Utilities) (press Command-Spacebar and type "Terminal" to get there faster).
  onisplit -extract:dae dest_dir ..\GameDataFolder\level0_Final\ONCCkonoko_generic.oni
This will produce an ONCCkonoko_generic.dae collada file in the directory dest_dir plus the tga texture files used by the specified character.


Note: Blender's Collada importer/exporter is buggy, so you will need to add the options -noanim and -zup when extracting collada files for use with Blender:
===OniSplit syntax===
  onisplit -extract:dae dest_dir -noanim -zup ..\GameDataFolder\level0_Final\ONCCkonoko_generic.oni
The basic syntax is:
-noanim prevents the export of the default idle animation. That's needed because Blender doesn't import animated objects correctly.
{|
-zup exports a collada file with a coordinate system where Z axis points up instead of the default (Y up). This is needed because Blender uses Z up but the importer gets it wrong and convert to something else.
|-
|'''Windows'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em; padding:0.15em">OniSplit.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">-create:trbs</span> <span style="background:rgb(255,156,156); border-radius:0.33em; padding:0.15em">C:\Games\Oni\SomeFolder</span> <span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">-normals</span> <span style="background:rgb(156,255,156); border-radius:0.33em; padding:0.15em">C:\Games\Oni\Modding\TRBSMyNewChar.dae</span></tt>
|-
|'''Mac'''||<tt><span style="background:rgb(235,235,235); border-radius:0.33em; padding:0.15em">mono OniSplit.exe</span> <span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">-create:trbs</span> <span style="background:rgb(255,156,156); border-radius:0.33em; padding:0.15em">/Games/Oni/SomeFolder</span> <span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">-normals</span> <span style="background:rgb(156,255,156); border-radius:0.33em; padding:0.15em">/Games/Oni/Modding/TRBSMyNewChar.dae</span></tt>
|}


To create a TRBS file, use the following command:  
Here's how it breaks down:
  onisplit -create:trbs ..\GameDataFolder\level0_Final ONCCkonoko_generic.dae
{|
This will create the TRBSkonoko_generic.oni file in dest_dir.
! style="width:130px"|
|- valign="top"
|<span style="background:rgb(235,235,235); border-radius:0.33em; padding:0.15em">'''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.
|-
|<span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">'''Option'''</span>||The command.
|- valign="top"
|<span style="background:rgb(255,156,156); border-radius:0.33em; padding:0.15em">'''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>
|-
|<span style="background:rgb(175,175,255); border-radius:0.33em; padding:0.15em">'''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; padding:0.15em">'''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.
|}


Options include
===CLI tips===
  -normals autogenerate normals.
*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.
  -cel generate a shell to give the effect of cel shading.


Example
*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.
  onisplit -create:trbs ..\GameDataFolder\level0_Final -normals ONCCkonoko_generic.dae


For more detailed information about importing characters, please this page: [[AE:Importing character models]]
===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.


===Export/Import xml===
===Spaces in paths===
Currently xml export/import is limited to files that do not have raw/sep parts.  Some files that currently work are [[ONCC]], [[TRAC]] and [[TRMA]]. The ability to modify these files in a text editor opens the door to easily changing character parameters, combat moves and textures without resorting to hex editing.
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:


To export a file to .xml
'''C:\Games\Oni\>'''OniSplit.exe -list "My Mod Folder\level5_Final.dat"
  onisplit -extract:xml xml_dir ..\GameDataFolder\level0_Final\ONCCstriker_hard_3.oni


To import an .oni from .xml file
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:
  onisplit -create ..\GameDataFolder\level0_Final ONCCstriker_hard_3.xml


===OniSplit commands===
'''MyMac%''' mono OniSplit.exe -list My\ Mods\ \(In\ Progress\)/level5_Final.dat
A list of commands can be found be entering OniSplit -help
       
        -export <directory>            Export a Oni .dat file to directory
        -import <directory>            Import a Oni .dat file from directory
                                        Target file format is determined from source files (when possible)
        -import:sep <directory>        Import a Oni .dat file from directory
                                        Create a .dat file that uses .raw and .sep binary files (Mac and PC Demo)
        -import:nosep <directory>      Import a Oni .dat file from directory
                                        Create a .dat file that uses only .raw binary file (PC)


        -extract:dds <directory>        Extracts all textures (TXMP) from a Oni .dat/.oni file in DDS format
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 ;-)
        -extract:tga <directory>        Extracts all textures (TXMP) from a Oni .dat/.oni file in TGA format
        -extract:png <directory>        Extracts all textures (TXMP) from a Oni .dat/.oni file in PNG format
        -extract:wav <directory>        Extracts all sounds (SNDD) from a Oni .dat/.oni file in WAV format
        -extract:aif <directory>        Extracts all sounds (SNDD) from a Oni .dat/.oni file in AIF format
        -extract:txt <directory>        Extracts all subtitles (SUBT) from a Oni .dat/.oni file in TXT format
        -extract:obj <directory>        Extracts all M3GM and ONCC instances to Wavefront OBJ files
        -extract:dae <directory>        Extracts all M3GM and ONCC instances to Collada files
        -extract:xml <directory>        Extracts all instances to XML files


        -create:txmp <directory> [-genmipmaps] [-nouwrap] [-novwrap] [-format:bgr32|bgra32|bgr555|bgra5551|bgra4444|dxt1] [-envmap:texture_name] image_file
===Reading the commands below===
        -create:m3gm <directory> [-tex:texture_name] obj_file
*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.
        -create:trbs <directory> dae_file
        -create:subt <directory> txt_file
        -create <directory> xml_file    Creates an .oni file from an XML file


        -copy <directory>               Copy an exported .oni file and its dependencies to directory
*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 "/".
        -move <directory>               Move an exported .oni file and its dependencies to directory
        -move:overwrite <directory>     Move an exported .oni file and its dependencies to directory
                                        Overwrites any existing files
        -move:delete <directory>       Move an exported .oni file and its dependencies to directory
                                        Deletes files at source when they already exist at destination
        -deps                          Get a list of exported .oni files the specified files depends on
        -version                        Print OniSplit versions


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


Note: For Mac users the command is:
==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"|<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>
|-
|<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.


  mono onisplit.exe (Also change every \ to /)
===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
|}


===Download links===
===Conversion between .oni/.dat and 3rd party formats===
* [http://edt.oni2.net/OS/OniSplit_v0.9.14.zip Latest version of OniSplit v0.9.14]<br>
====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><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)
|}
 
====Models====
[[M3GM]]s, [[ONWC]]s, [[ONCC]]s can be exported to the Wavefront .obj and COLLADA .dae formats. For details see [[Importing character models]] and [[Importing weapon models]]. The generic <tt>-extract</tt> commands can work with .oni files (a single file, or several files if you use the wildcard), or rip all the TXMP from a .dat file. TRBS and ONCC support additional <tt>-noanim</tt> and <tt>-anim</tt> options for <tt>-extract:dae</tt>; see [[Importing character models]] for details. Imported geometry must only contain triangles.
{|
! style="width:540px"|
|- valign="top"
|<code>-extract:obj <destination directory> <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Wavefront OBJ files
|- valign="top"
|<code>-extract:dae <destination directory> [-noanim] <dat/oni file></code>||Extracts 3D data in .oni file (or all M3GM, ONWC and ONCC instances in a .dat) into Collada DAE files
|-
|<code>-create:m3gm <destination directory> [-tex:texture_name] <OBJ file></code>||Creates a M3GM .oni from an .obj file
|-
|<code>-create:trbs <destination directory> [-cel] [-normals] <DAE file></code>||Creates a TRBS .oni from a .dae file
|}
 
Note on -noanim parameter: Normally OniSplit exports the character with an idle animation. If you use -noanim the character is exported in "I" pose, also the pelvis has the coordinates x=0, y=0, z=0.
 
====Levels====
OniSplit can convert AKEV files (level geometry) and the associated file types to and from DAE format:
{|
|<code>-extract:dae <destination directory> <AKEV.oni file></code>||Extracts 3D data in AKEV and related resources from dependencies into Collada file
|}
 
 
The next two steps are used on a folder in which you have placed the DAE and XML-formatted instances of the required files, as well as textures in TGA format. See [http://oni.bungie.org/forum/viewtopic.php?id=1515 HERE] for details.
{|
|- valign="top"
|<code>-create <destination directory><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!)
|}
 
====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
|}


===Requirements===
====Blender support====
OniSplit requires .NET for PC and the mono framework for Mac OS X.
[[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.


* [http://www.microsoft.com/downloads/details.aspx?familyid=0856eacb-4362-4b0d-8edd-aab15c5e04f5&displaylang=en .NET]
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]].  
* [ftp://www.go-mono.com/archive/1.2.6/macos-10-universal/6/MonoFramework-1.2.6_6.macos10.novell.universal.dmg Latest version of mono (requires OS X 10.4+)]
* [http://edt.oni2.net/AE/MonoFramework10.3.dmg Mono for OS X 10.3]


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

Latest revision as of 22:43, 5 December 2023

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.

Subpages: Change log (past versions), WIP notes (upcoming versions)

Getting it

Download links

  • Latest release of OniSplit: v0.9.99.2 (source code)
  • 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

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

          
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 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.
  • 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 OniSplit.exe -create:trbs C:\Games\Oni\SomeFolder -normals C:\Games\Oni\Modding\TRBSMyNewChar.dae
Mac mono OniSplit.exe -create:trbs /Games/Oni/SomeFolder -normals /Games/Oni/Modding/TRBSMyNewChar.dae

Here's how it breaks down:

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.
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.
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 -create 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 * 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, \. Also, other characters like ( 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 -help option. You should also use -version 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 \s to /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.

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

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 -blender flag.

For more detailed information on how to use the -blender flag, please check Blender specific OniSplit information.

Retrieved from "https://wiki.oni2.net/w/index.php?title=OniSplit&oldid=41805"