OniSplit: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (using hatnote template; subpages should go below lede)
m (link fix)
 
(4 intermediate revisions by 2 users not shown)
Line 7: Line 7:
==Getting it==
==Getting it==
===Download links===
===Download links===
* Latest release of OniSplit: [http://mods.oni2.net/node/38 v0.9.99.2] ([http://websvn.illy.bz/dl.php?repname=Oni2&path=%2FOniSplit%2F&isdir=1 source code])
* 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.'''
* 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.'''


Line 32: Line 32:
==Beginner's tips==
==Beginner's tips==
{{Divhide|show=yes|For users new to the command line or to OniSplit}}
{{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.
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).
On Macs, the command line is found in the Terminal app (/Applications/Utilities) (press Command-Spacebar and type "Terminal" to get there faster).
Line 97: Line 101:
! style="width:430px"|
! 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>-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 <destination directory> <dat file></code>||Breaks .dat file into .oni files
Line 196: Line 200:
|<code>-create <destination directory> <XML file></code>||Creates an .oni file from an XML file
|<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]]
[[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

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.