Tools

AssetImporter

Loads various 3D formats supported by Open Asset Import Library (http://assimp.sourceforge.net/) and saves Urho3D model, animation, material and scene files out of them. For the list of supported formats, look at http://assimp.sourceforge.net/main_features_formats.html.

An alternative export path for Blender is to use the Urho3D add-on (https://github.com/reattiva/Urho3D-Blender).

Usage:

AssetImporter <command> <input file> <output file> [options]

Commands:
model       Output a model
anim        Output animation(s)
scene       Output a scene
node        Output a node and its children (prefab)
dump        Dump scene node structure. No output file is generated
lod         Combine several Urho3D models as LOD levels of the output model
            Syntax: lod <dist0> <mdl0> <dist1 <mdl1> ... <output file>

Options:
-b          Save scene in binary format, default format is XML
-j          Save scene in JSON format, default format is XML
-h          Generate hard instead of smooth normals if input has no normals
-i          Use local ID's for scene nodes
-l          Output a material list file for models
-na         Do not output animations
-nm         Do not output materials
-nt         Do not output material textures
-nc         Do not use material diffuse color value, instead output white
-nh         Do not save full node hierarchy (scene mode only)
-ns         Do not create subdirectories for resources
-nz         Do not create a zone and a directional light (scene mode only)
-nf         Do not fix infacing normals
-ne         Do not save empty nodes (scene mode only)
-mb <x>     Maximum number of bones per submesh. Default 64
-p <path>   Set path for scene resources. Default is output file path
-r <name>   Use the named scene node as root node
-f <freq>   Animation tick frequency to use if unspecified. Default 4800
-o          Optimize redundant submeshes. Loses scene hierarchy and animations
-s <filter> Include non-skinning bones in the model's skeleton. Can be given a
            case-insensitive semicolon separated filter list. Bone is included
            if its name contains any of the filters. Prefix filter with minus
            sign to use as an exclude. For example -s "Bip01;-Dummy;-Helper"
-t          Generate tangents
-v          Enable verbose Assimp library logging
-eao        Interpret material emissive texture as ambient occlusion
-cm         Check and do not overwrite if material exists
-ct         Check and do not overwrite if texture exists
-ctn        Check and do not overwrite if texture has newer timestamp
-am         Export all meshes even if identical (scene mode only)
-bp         Move bones to bind pose before saving model
-split <start> <end> (animation model only)
            Split animation, will only import from start frame to end frame

The material list is a text file, one material per line, saved alongside the Urho3D model. It is used by the scene editor to automatically apply the imported default materials when setting a new model for a StaticModel, StaticModelGroup, AnimatedModel or Skybox component, and can also be manually invoked by calling ApplyMaterialList(). The list files can safely be deleted if not needed.

In model or scene mode, the AssetImporter utility will also automatically save non-skeletal node animations into the output file directory.

OgreImporter

Loads OGRE .mesh.xml and .skeleton.xml files and saves them as Urho3D .mdl (model) and .ani (animation) files. For other 3D formats and whole scene importing, see AssetImporter instead. However that tool does not handle the OGRE formats as completely as this.

Usage:

OgreImporter <input file> <output file> [options]

Options:
-l      Output a material list file
-na     Do not output animations
-nm     Do not output morphs
-r      Output only rotations from animations
-s      Split each submesh into own vertex buffer
-t      Generate tangents
-mb <x> Maximum number of bones per submesh, default 64

Note: outputting only bone rotations may help when using an animation in a different model, but if bone position changes have been used for effect, the animation may become less lively. Unpredictable mutilations might result from using an animation in a model not originally intended for, as Urho3D does not specifically attempt to retarget animations.

PackageTool

Examines a directory recursively for files and subdirectories and creates a PackageFile. The package file can be added to the ResourceCache and used as if the files were on a (read-only) filesystem. The file data can optionally be compressed using the LZ4 compression library.

Use caution when using package files on Android, as the .apk is already a package itself, where arbitrary seeks can perform poorly due to compression already being used. Experimentally it looks that on Android it can be favorable to compress the package, because in that case the .apk packaging may skip its own compression, allowing better seek & read performance.

Usage:

PackageTool <directory to process> <package name> [basepath] [options]

Options:
-c      Enable package file LZ4 compression
-q      Enable quiet mode

Basepath is an optional prefix that will be added to the file entries.

Alternate output usage:

PackageTool <output option> <package name>

Output option:
-i      Output package file information
-l      Output file names (including their paths) contained in the package
-L      Similar to -l but also output compression ratio (compressed package file only)

When PackageTool runs, it will go inside the source directory, then look for subdirectories and any files. Paths inside the package will by default be relative to the source directory, but if an extra path prefix is desired, it can be specified by the optional basepath argument.

For example, this would convert all the resource files inside the Urho3D Data directory into a package called Data.pak (execute the command from the bin directory)

PackageTool Data Data.pak

The -c option enables LZ4 compression on the files. The -q option enables the operation to be performed without sending output to the standard output stream.

RampGenerator

Creates 1D and 2D ramp textures for use in light attenuation and spotlight spot shapes.

Usage:

RampGenerator <output file> <width> <power> [dimensions]

The output is saved in PNG format. The power parameter is fed into the pow() function to determine ramp shape; higher value gives more brightness and more abrupt fade at the edge.

SpritePacker

Takes a series of images and packs them into a single texture and creates a sprite sheet xml file.

Usage:

SpritePacker -options <input file> <input file> <output png file>
Options:
    -h Shows this help message.
    -px Adds x pixels of padding per image to width.
    -py Adds y pixels of padding per image to height.
    -ox Adds x pixels to the horizontal position per image.
    -oy Adds y pixels to the horizontal position per image.
    -frameHeight Sets a fixed height for image and centers within frame.
    -frameWidth Sets a fixed width for image and centers within frame.
    -trim Trims excess transparent space from individual images offsets by frame size.
    -xml 'path' Generates an SpriteSheet xml file at path.
    -debug Draws allocation boxes on sprite.

ScriptCompiler

Compiles AngelScript file(s) to binary bytecode for faster loading. Can also dump the Script API in Doxygen format.

Usage:

ScriptCompiler <input file> [resource path for includes]
ScriptCompiler -dumpapi <Doxygen output file> [C header output file]

The output files are saved with the extension .asc (compiled AngelScript.) binary files are not automatically loaded instead of the text format (.as) script files, instead resource requests and resource references in objects need to point to the compiled files. In a final build of an application it may be convenient to simply replace the text format script files with the compiled scripts.

The script API dump mode can be used to replace the 'ScriptAPI.dox' file in the 'Docs' directory. If the output file name is not provided then the script API would be dumped to standard output (console) instead.