Difference between revisions of "W4 AssetCreator"

From Ciliz|W4
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
 
== Scope ==
 
== Scope ==
The W4 game engine uses its own asset storage format. Therefore, before using any fbx asset, it has to be converted. This can be done using the W4AssetCreator tool that comes with the W4 SDK.
+
The W4 game engine uses its own asset storage format. Therefore, most resources have to be packed before use. This can be done using the W4AssetCreator console application that comes with the W4 SDK.
  
W4AssetCreator converts assets from Autodesk FBX (.fbx) format. Other formats are not supported.
+
W4AssetCreator works in two modes:
 +
* Configuration Mode (see further details below);
 +
* Single Mode (this is a single asset mode that is currently not implemented).
  
 
=== Mesh Example ===
 
=== Mesh Example ===
Line 31: Line 33:
  
 
== Short manual ==
 
== Short manual ==
=== W4AssetCreator parameters ===
+
=== Common parameters ===
Below is the output of the application (when launched without parameters):
+
Parameters that can be used in any mode:
  
<div style="font-size:80%;>
+
* -h, --help - shows available parameters;
  W4 Asset Creator
+
* --output-directory - sets the output folder:
  Usage:
+
** SingleMode - the folder where the asset is placed,
  ./W4AssetCreator [OPTION...] [name] [output]
+
** ConfigurationMode - the folder into which the files will be synchronized and the assets are created according to the configuration file.
 
 
  FLAGS options:
 
  -h, --help           print help
 
  --material arg  add material to asset (default: "")
 
  --root arg      root directory for all relative paths (except output)
 
  (default: /Users/p.steinberg/dev/w4-framework)
 
  --image arg      add image to asset (default: "")
 
  --particles arg  add particles to asset (default: "")
 
  --fbx arg        input fbx file
 
  --pn arg        name of plugin (default: "")
 
  --pp arg        plugin params (default: "")
 
  --scale arg      scale for converter
 
  --no-animation  no export animations from input fbx file
 
  --animation arg  add animation from fbx file. format
 
  'path[:%stackName%=%animationName%;...]' (default: "")
 
 
 
  POSITIONAL options:
 
  --name arg    asset name, default is 'asset' (default: asset)
 
  --output arg  output directory, default is current directory. Result
 
  output is %output%/%name%.w4a file (default:
 
  /Users/p.steinberg/dev/w4-framework)
 
</div>
 
  
'''Additional description:'''
+
=== Configuration Mode ===
 +
This mode synchronizes resources located in the folder specified in the configuration file with the '''--output-directory''' folder (if the configuration file does not exist, then the folder of the configuration file is used).
  
'''--root''' - please, pay attention to this parameter. If it is not specified, all relative paths are taken from the folder from which the application is launched
+
In this mode, W4AssetCreator takes the following input parameters:
  
'''--fbx''' - path to *.fbx file that will be converted to asset, you can specify only one
+
* --config - the path to the configuration file. If the file does not exist, it is generated automatically;
 +
* --create-symlinks - instead of copying files, symlinks are created;
 +
* --create-hardlinks - instead of copying files, hardinks are created;
 +
* --cache-directory - if the parameter is set, then the configuration and assets are cached and not recreated if there were no changes in the files and / or configuration.
  
'''--scale''' - scale for all entities exported from (--fbx)
+
=== Default configuration file creation rules ===
 +
Ignored files:
  
'''--no-animation''' - if set, no animations are exported from the fbx file specified in the argument (--fbx)
+
* “AssetCreator[.CONFIG].config”
 +
* “*.vs”
 +
* “*.fs”
  
'''--animation''' - adding animations to the asset (animations are located separately). If desired, you can rename the animation when adding (see the format description above)
+
Files from which individual assets are created:
  
'''--material''' - path to the material JSON that will be added to the asset (you can specify several)
+
* “*.fbx” - a separate asset (path/to/fbx/file.w4a) is created for each file
  
'''--image''' - path to the image that will be added to the asset (you can specify several)
+
Files that are placed in the asset by default:
  
'''--particles''' - path to the description of particles in json format (you can specify several)
+
* pictures (OS should define their mime-type as image / something)
 +
* particles (*.part)
 +
* materials (*.mat)
  
'''--pn, --pp''' - arguments for the plugin system (TBD)
+
The rest of the files are marked for synchronization with the output folder.
 
 
There are two positional arguments:
 
  
* Name of the created asset.
+
=== Configuration file description ===
* Path to the folder in which the asset will be located.
+
The configuration file is a json file with the following root fields:
  
=== Usage Example ===
+
* path - path to the project resources directory;
<div style="font-size:80%;>
+
* version - W4Framework resources version;
  W4AssetCreator --root=path/to/resources/root \
+
* rules - all rules for working with assets.
          --material=resources/materials/back1.mat,resources/materials/crowd.mat,resources/materials/dissolve_twoTextures.mat \
+
 
          --material=resources/materials/paperboy.mat,resources/materials/platform.mat,resources/materials/postament.mat,resources/materials/step.mat \
+
There are 3 basic rules for working with assets:
          --animation="A_PaperBoy_Dance2.fbx:Take 001=Crewman,A_PaperBoy_Flip.fbx:Take 001=Flip" \
+
 
          --image=resources/textures/dissolve.png,resources/textures/T_Homer_Face_D.png,resources/textures/T_PaperBoy_Body_D.png \
+
* “skip” - [array] list of ignored files
          --image=resources/textures/T_PaperBoy_Head_D.png,resources/textures/T_PaperBoy_LeftHand_D.png,resources/textures/T_PaperBoy_RightHand_D.png \
+
* “pass” - [array] list of files to be copied (or symlink will be created on them, with --create-symlinks)
          --image=resources/textures/T_PaperBoy_Pants_D.png,resources/textures/T_trio_Head_D.png \
+
* “assets” - [object] - rules for generating assets - key:value (relative path to the asset : rules for this asset)
          --image=resources/textures/T_PaperNinja_Body_D.png,resources/textures/T_PaperNinja_Pants_D.png,resources/textures/T_PaperNinja_LeftHand_D.png \
+
 
          --image=resources/photos/W4_01.jpg,resources/photos/W4_02.jpg,resources/photos/W4_03.jpg,resources/photos/W4_04.jpg,resources/photos/W4_05.jpg \
+
Rules for generating assets.:
          --image=resources/photos/W4_06.jpg,resources/photos/W4_07.jpg,resources/photos/W4_08.jpg,resources/photos/W4_09.jpg,resources/photos/W4_10.jpg \
+
 
          --image=resources/photos/W4_11.jpg,resources/photos/W4_12.jpg,resources/photos/W4_13.jpg,resources/photos/W4_14.jpg,resources/photos/W4_15.jpg \
+
* “images” - [array] a list of files that are added to the asset as pictures (w4::resources::Image)
          --image=resources/photos/W4_16.jpg,resources/photos/W4_17.jpg,resources/photos/W4_18.jpg,resources/photos/W4_19.jpg \
+
* “binaries” - [array] a list of files that are added to the asset as binaries (w4::resources::Binary)
          --fbx=SK_PaperBoy_T_Pose.fbx \
+
* “materials” - [array] a list of files that are added to the asset as materials  (w4::resources::Material)
          --no-animation \
+
* “particles” - [array] a list of files that are added to the asset as particles (w4::render::ParticlesEmitter)
          AssetName \
+
* “models” - [object] a list of model source files (fbx), which are converted to W4 format and are available in the asset as a node tree. A list of conversion parameters is passed as a value
          asset/destination/directory
+
* “animations” - [object] a list of model source files (fbx), from which ONLY skeletal animations are extracted. A list of conversion parameters is passed as a value
</div>
+
 
 +
List of models parameters:
 +
 
 +
* no-animation - do not export skeletal animations from this file
 +
* scale=%float% - apply scaling to models / animations
 +
* add-animation=%AnimationName% - add “AnimationName” animation to animation list for each SkinnedMesh in this model. This animation must be added from one of the files located in the "animations" section
 +
* rename-animation=%PrevName%=%NewName% - rename animation PrevName to animation NewName
 +
 
 +
List of animations parameters:
 +
 
 +
* scale=%float% - apply scaling to animations
 +
* rename=%PrevName%=%NewName% - rename animation PrevName to animation NewName
 +
* split=%animationName%:%beginFrame1%-%endFrame1%=%partName1%,%beginFrame2%-%endFrame2%=%partName2% - replace the animationName animation with parName1, partName2, and so on. parNames are part of the animationName from the beginFrameM frame to the endFrameM frame
 +
 +
=== Configuration File Example ===
 +
<syntaxhighlight lang="json">
 +
{
 +
    "path": ".",
 +
    "rules": {
 +
        "assets": {
 +
            "Paperboy.w4a": {
 +
                "animations": {
 +
                    "animations/A_PaperBoy_Dance2.fbx": [
 +
                        "rename=Take 001=Crewman"
 +
                    ],
 +
                    "animations/A_PaperBoy_Flip.fbx": [
 +
                        "rename=Take 001=Flip"
 +
                    ]
 +
                },
 +
                "models": {
 +
                    "SK_PaperBoy_T_Pose.fbx": [
 +
                        "no-animation",
 +
                        "add-animation=Crewman",
 +
                        "add-animation=Flip"
 +
                    ]
 +
                }
 +
            },
 +
            "default.w4a": {
 +
                "images": [
 +
                    "photos/W4_05.jpg",
 +
                    "photos/W4_03.jpg",
 +
                    "textures/T_PaperBoy_Pants_D.png",
 +
                    "photos/W4_02.jpg",
 +
                    "photos/W4_12.jpg",
 +
                    "photos/W4_18.jpg",
 +
                    "photos/W4_15.jpg",
 +
                    "photos/W4_13.jpg",
 +
                    "photos/W4_14.jpg",
 +
                    "textures/T_trio_Head_D.png",
 +
                    "photos/W4_01.jpg",
 +
                    "textures/T_PaperNinja_LeftHand_D.png",
 +
                    "photos/W4_11.jpg",
 +
                    "photos/W4_06.jpg",
 +
                    "textures/T_PaperBoy_RightHand_D.png",
 +
                    "textures/T_PaperBoy_Head_D.png",
 +
                    "textures/dissolve.png",
 +
                    "textures/T_PaperBoy_LeftHand_D.png",
 +
                    "textures/T_PaperNinja_Body_D.png",
 +
                    "photos/W4_07.jpg",
 +
                    "photos/W4_08.jpg",
 +
                    "photos/W4_10.jpg",
 +
                    "photos/W4_17.jpg",
 +
                    "textures/T_PaperBoy_Body_D.png",
 +
                    "textures/T_Homer_Face_D.png",
 +
                    "photos/W4_19.jpg",
 +
                    "photos/W4_09.jpg",
 +
                    "textures/T_PaperNinja_Pants_D.png",
 +
                    "photos/W4_16.jpg",
 +
                    "photos/W4_04.jpg"
 +
                ],
 +
                "materials": [
 +
                    "materials/back1.mat",
 +
                    "materials/dissolve_twoTextures.mat",
 +
                    "materials/step.mat",
 +
                    "materials/postament.mat",
 +
                    "materials/paperboy.mat",
 +
                    "materials/crowd.mat",
 +
                    "materials/platform.mat"
 +
                ]
 +
            }
 +
        },
 +
        "skip": [
 +
            "materials/shaders/platform.vs",
 +
            "materials/shaders/paperboy.vs",
 +
            "materials/shaders/paperboy.fs",
 +
            "materials/shaders/back1.fs",
 +
            "materials/shaders/postament.vs",
 +
            "materials/shaders/back.vs",
 +
            "materials/shaders/crowd.fs",
 +
            "materials/shaders/dissolve_twoTextures.fs",
 +
            "materials/shaders/step.vs",
 +
            "materials/shaders/dissolve.vs",
 +
            "materials/shaders/cube.fs",
 +
            "AssetCreator.config"
 +
        ]
 +
    },
 +
    "version": "0.2"
 +
}
 +
</syntaxhighlight>

Latest revision as of 17:23, 22 December 2020

Scope

The W4 game engine uses its own asset storage format. Therefore, most resources have to be packed before use. This can be done using the W4AssetCreator console application that comes with the W4 SDK.

W4AssetCreator works in two modes:

  • Configuration Mode (see further details below);
  • Single Mode (this is a single asset mode that is currently not implemented).

Mesh Example

Let’s take the Utah teapot as an example. If you view the file using the utility Autodesk FBX Review, you will see something similar to the following figure.

cb84552c-5001-4127-9d9d-1e93f9c96696.png

Pay attention to the orientation of the teapot spout when viewing fbx. As a result, the same teapot is displayed, but with a slight difference.

3aa4d02a-5152-44d6-9168-13a155f1b049.png

If you compare the drawings, you may notice that the spout of the teapot has changed its directed after the program execution. This happens due to differences in coordinate systems.

The FBX coordinate system Scene Axis and Unit Conversion is right-handed (with the Y pointing up), whereas W4 coordinate system is left-handed (the the Y axis is also pointing up).

Animated mesh Exmple

Take, for example, Rigged Hand.

If you view it using Autodesk FBX Review you will see approximately the following:

As a result of conversion, the following animation is shown:

Short manual

Common parameters

Parameters that can be used in any mode:

  • -h, --help - shows available parameters;
  • --output-directory - sets the output folder:
    • SingleMode - the folder where the asset is placed,
    • ConfigurationMode - the folder into which the files will be synchronized and the assets are created according to the configuration file.

Configuration Mode

This mode synchronizes resources located in the folder specified in the configuration file with the --output-directory folder (if the configuration file does not exist, then the folder of the configuration file is used).

In this mode, W4AssetCreator takes the following input parameters:

  • --config - the path to the configuration file. If the file does not exist, it is generated automatically;
  • --create-symlinks - instead of copying files, symlinks are created;
  • --create-hardlinks - instead of copying files, hardinks are created;
  • --cache-directory - if the parameter is set, then the configuration and assets are cached and not recreated if there were no changes in the files and / or configuration.

Default configuration file creation rules

Ignored files:

  • “AssetCreator[.CONFIG].config”
  • “*.vs”
  • “*.fs”

Files from which individual assets are created:

  • “*.fbx” - a separate asset (path/to/fbx/file.w4a) is created for each file

Files that are placed in the asset by default:

  • pictures (OS should define their mime-type as image / something)
  • particles (*.part)
  • materials (*.mat)

The rest of the files are marked for synchronization with the output folder.

Configuration file description

The configuration file is a json file with the following root fields:

  • path - path to the project resources directory;
  • version - W4Framework resources version;
  • rules - all rules for working with assets.

There are 3 basic rules for working with assets:

  • “skip” - [array] list of ignored files
  • “pass” - [array] list of files to be copied (or symlink will be created on them, with --create-symlinks)
  • “assets” - [object] - rules for generating assets - key:value (relative path to the asset : rules for this asset)

Rules for generating assets.:

  • “images” - [array] a list of files that are added to the asset as pictures (w4::resources::Image)
  • “binaries” - [array] a list of files that are added to the asset as binaries (w4::resources::Binary)
  • “materials” - [array] a list of files that are added to the asset as materials (w4::resources::Material)
  • “particles” - [array] a list of files that are added to the asset as particles (w4::render::ParticlesEmitter)
  • “models” - [object] a list of model source files (fbx), which are converted to W4 format and are available in the asset as a node tree. A list of conversion parameters is passed as a value
  • “animations” - [object] a list of model source files (fbx), from which ONLY skeletal animations are extracted. A list of conversion parameters is passed as a value

List of models parameters:

  • no-animation - do not export skeletal animations from this file
  • scale=%float% - apply scaling to models / animations
  • add-animation=%AnimationName% - add “AnimationName” animation to animation list for each SkinnedMesh in this model. This animation must be added from one of the files located in the "animations" section
  • rename-animation=%PrevName%=%NewName% - rename animation PrevName to animation NewName

List of animations parameters:

  • scale=%float% - apply scaling to animations
  • rename=%PrevName%=%NewName% - rename animation PrevName to animation NewName
  • split=%animationName%:%beginFrame1%-%endFrame1%=%partName1%,%beginFrame2%-%endFrame2%=%partName2% - replace the animationName animation with parName1, partName2, and so on. parNames are part of the animationName from the beginFrameM frame to the endFrameM frame

Configuration File Example

{
    "path": ".",
    "rules": {
        "assets": {
            "Paperboy.w4a": {
                "animations": {
                    "animations/A_PaperBoy_Dance2.fbx": [
                        "rename=Take 001=Crewman"
                    ],
                    "animations/A_PaperBoy_Flip.fbx": [
                        "rename=Take 001=Flip"
                    ]
                },
                "models": {
                    "SK_PaperBoy_T_Pose.fbx": [
                        "no-animation",
                        "add-animation=Crewman",
                        "add-animation=Flip"
                    ]
                }
            },
            "default.w4a": {
                "images": [
                    "photos/W4_05.jpg",
                    "photos/W4_03.jpg",
                    "textures/T_PaperBoy_Pants_D.png",
                    "photos/W4_02.jpg",
                    "photos/W4_12.jpg",
                    "photos/W4_18.jpg",
                    "photos/W4_15.jpg",
                    "photos/W4_13.jpg",
                    "photos/W4_14.jpg",
                    "textures/T_trio_Head_D.png",
                    "photos/W4_01.jpg",
                    "textures/T_PaperNinja_LeftHand_D.png",
                    "photos/W4_11.jpg",
                    "photos/W4_06.jpg",
                    "textures/T_PaperBoy_RightHand_D.png",
                    "textures/T_PaperBoy_Head_D.png",
                    "textures/dissolve.png",
                    "textures/T_PaperBoy_LeftHand_D.png",
                    "textures/T_PaperNinja_Body_D.png",
                    "photos/W4_07.jpg",
                    "photos/W4_08.jpg",
                    "photos/W4_10.jpg",
                    "photos/W4_17.jpg",
                    "textures/T_PaperBoy_Body_D.png",
                    "textures/T_Homer_Face_D.png",
                    "photos/W4_19.jpg",
                    "photos/W4_09.jpg",
                    "textures/T_PaperNinja_Pants_D.png",
                    "photos/W4_16.jpg",
                    "photos/W4_04.jpg"
                ],
                "materials": [
                    "materials/back1.mat",
                    "materials/dissolve_twoTextures.mat",
                    "materials/step.mat",
                    "materials/postament.mat",
                    "materials/paperboy.mat",
                    "materials/crowd.mat",
                    "materials/platform.mat"
                ]
            }
        },
        "skip": [
            "materials/shaders/platform.vs",
            "materials/shaders/paperboy.vs",
            "materials/shaders/paperboy.fs",
            "materials/shaders/back1.fs",
            "materials/shaders/postament.vs",
            "materials/shaders/back.vs",
            "materials/shaders/crowd.fs",
            "materials/shaders/dissolve_twoTextures.fs",
            "materials/shaders/step.vs",
            "materials/shaders/dissolve.vs",
            "materials/shaders/cube.fs",
            "AssetCreator.config"
        ]
    },
    "version": "0.2"
}