AssetBaker 1120

From PopcornFX
Jump to navigation Jump to search

See also : Editor interface overview.

This page is for version v1.12.0 and above
For the latest version of PopcornFX, see: AssetBaker
For previous versions of PopcornFX, see the following pages:


Overview

The Popcorn editor packs contain the offline resource files that make-up your effects.
Although the .pkfx files inside it can be directly loaded into your game with the popcorn runtime, They are to the runtime FX what .psd files are to runtime textures: you probably don't want your final game to load .psd files directly.

The asset baker is a command-line tool used to bake and deploy popcorn packs into a runtime-friendly layout. It allows you to specify a source pack, and various platforms / output packs.

It currently is only available by command-line, invoked through batch files. It will be integrated in Popcorn editor v1.5.4.
Depending on your licensing option, you can also get the AssetBakerLib, so you can link it in your projects, and invoke it directly from your own deployment toolchain if necessary.


Command line options

-v Print the AssetBaker build version and quit
-p=path 'path' = path to the source pack, can have double-quotes. Should only appear once, ex: -p="C:\popcorn\test pack"
-o=build:path 'platform' = one of the target platforms, 'path' = the output pack path. Can appear multiple times. ex: -o=PS3:"T:\builds\PS3\test pack"
-i=path 'path' = path to the input asset file to bake, relative to the source pack. Can appear multiple times. ex: -i="Particles/beer.pkfx"
-I=path Same as -i, but also bakes all the asset's dependencies.
-d=path 'path' = path to the input asset file, relative to the source pack. Prints the asset's dependencies.
-cfg=path 'path' = path to an asset config file. relative to the source pack. Interpretation depends on context. If specified before any -i args, will be treated as a global config file. Otherwise, will be applied to the previous file.
-s enables silent mode: Baker does not print any output.
-f force full rebuild of all assets.
-h shows this help screen.


Example .bat usage

Assuming we have the following directory layout:

(The editor authors effects directly in "H:\popcorn-packs\Editor\Packs\", and we have a single pack named "Game1_Spells"

Asset baker : source folder example


And the following "BakeBacks.bat" 

@echo off
echo Launching Popcorn-Fx asset ovens...
PK-AssetBaker.exe -p="Packs\Game1_Spells" -o=x32:"..\builds\Game1Resources_x32\Particles\Spells" -o=x64:"..\builds\Game1Resources_x64\Particles\Spells" -i="Particles/*.pkfx" -i="Meshes/*.fbx" -i="Meshes/*.pkmm" -i=Textures/* -i=Sounds/* -i="LastRevision.txt"

pause


Let's dissect that command-line:

  1. -p="Packs\Game1_Spells"
    • gives the source-pack path (one per invocation of asset-baker)
  2. -o=x32:"..\builds\Game1Resources_x32\Particles\Spells"
    • asks to bake an "x32" configuration into directory "..\builds\Game1Resources_x32\Particles\Spells"
  3. -o=x64:"..\builds\Game1Resources_x64\Particles\Spells"
    • asks to bake an "x64" configuration into directory "..\builds\Game1Resources_x64\Particles\Spells"
  4. -i="Particles/*.pkfx"
    • asks to bake all resource files that match "%SOURCE_PACK%/Particles/*.pkfx" (case-insensitive)
  5. -i="Meshes/*.fbx"
    • asks to bake all resource files whose path match "%SOURCE_PACK%/Meshes/*.fbx" (case-insensitive)
  6. -i="Meshes/*.pkmm"
    • asks to bake all resource files whose path match "%SOURCE_PACK%/Meshes/*.pkmm" (case-insensitive)
  7. -i=Textures/*
    • asks to bake all resource files in the "Textures" directory in the source pack
  8. -i=Sounds/*
    • asks to bake all resource files in the "Textures" directory in the source pack
  9. -i="LastRevision.txt"
    • asks to bake the source pack's "dependencies.txt" file (straight copy)


Running the batch file:

Asset baker : command-line output


After running the batch file, the asset-baker will have produced the following output structure:

Asset baker : output folder example


You can of course chain any number of calls to the asset baker in your batch file, to bake multiple packs at once: 


@echo off
echo Launching Popcorn-Fx asset ovens...
PK-AssetBaker.exe -p="Packs\Game1_Spells" -o=x32:"..\builds\Game1Resources_x32\Particles\Spells" -o=x64:"..\builds\Game1Resources_x64\Particles\Spells" -i="Particles/*.pkfx" -i="Meshes/*.fbx" -i="Meshes/*.pkmm" -i=Textures/* -i=Sounds/* -i="LastRevision.txt"
PK-AssetBaker.exe -p="Packs\Game1_Atmospheric" -o=x32:"..\builds\Game1Resources_x32\Particles\Atmospheric" -o=x64:"..\builds\Game1Resources_x64\Particles\Atmospheric" -i="Particles/*.pkfx" -i="Meshes/*.fbx" -i="Meshes/*.pkmm" -i=Textures/* -i=Sounds/* -i="LastRevision.txt"
PK-AssetBaker.exe -p="Packs\Game1_WildLife" -o=x32:"..\builds\Game1Resources_x32\Particles\WildLife" -o=x64:"..\builds\Game1Resources_x64\Particles\WildLife" -i="Particles/*.pkfx" -i="Meshes/*.fbx" -i="Meshes/*.pkmm" -i=Textures/* -i=Sounds/* -i="LastRevision.txt"
pause


Important note on runtime popcorn meshes

You might have noticed when browsing for a mesh that the PopcornFX editor writes in the target object properties the path to a .pkmm file, NOT to an .fbx file.
This is because the runtime expects a 'pkmm' file, which is popcorn's runtime mesh format.


The editor also needs 'pkmm' files to correctly display them, it cannot directly use FBX files directly. Therefore, it creates pkmm files in "Cache/Meshes/".
NOTE: The Cache directory can be customized in the editor's project settings.
Using an editor pack as a runtime pack that contains meshes does not work because the runtime will try to load the pkmm files in "Meshes", whereas the editor pack has them in "Cache/Meshes".


The asset baker will correctly bake the FBX meshes from "%SOURCE_PACK%/Meshes/*.FBX" into "%BAKED_PACK%/Meshes/*.pkmm"


Builds and custom configs

The asset baker is architectured around "Resource ovens" that take care of baking a specific resource type. When given a specific resource, the asset-baker will choose the appropriate oven based on the resource extension. For example, *.pkfx files will be handled by the "Particle" oven.

You can tell the baker to bake for different build configurations. It will try to load the file Config/AssetBaker.pkcf in the source pack. That config file will tell the baker how to bake each type of asset based on the config. It contains one or multiple Oven configuration objects.

COvenBakeConfig_Base : Common properties

All ovens inherit from COvenBakeConfig_Base, and share these base properties:

Property name Default value Description
BakeTarget <empty> string, contains the name of the build target this config applies to. an empty string means all build targets
CommandLine_PreBake_Windows <empty> Command-line executed BEFORE the file has been baked, when the baker is run on a windows OS
CommandLine_PreBake_Linux <empty> Command-line executed BEFORE the file has been baked, when the baker is run on a linux OS
CommandLine_PreBake_MacOsX <empty> Command-line executed BEFORE the file has been baked, when the baker is run on a MacOsX OS
CommandLine_Windows <empty> Command-line executed AFTER the file has been baked, when the baker is run on a windows OS
CommandLine_Linux <empty> Command-line executed AFTER the file has been baked, when the baker is run on a linux OS
CommandLine_MacOsX <empty> Command-line executed AFTER the file has been baked, when the baker is run on a MacOsX OS
OverrideDefaultBakeWithCmdline false Do not execute default baking, only the CommandLine_* commands
AlwaysMkdirTarget false Always create the $(TargetDir) directory chain just after CommandLine_PreBake, even if OverrideDefaultBakeWithCmdline is active


The command-lines can contain the following special tokens:

  1. $(InputPath) : full path to the source texture, with the extension
  2. $(InputDir) : full path to the input directory
  3. $(InputExt) : extension of the original file, without the dot '.'
  4. $(FileName) : file-name, without extension
  5. $(TargetPath) : full path to the target file, with the original extension
  6. $(TargetDir) : full path to the target directory

You can use environment variables in the command-line, using the regular platform's syntax, and invoke SDK-specific texture conversion tools based on the platform (like gxt/gnf converters, do not hesitate to contact us if you have any trouble with this)

(See the Texture oven below for a specific example)


COvenBakeConfig_Texture

Used for texture resources.
Applied to: *.dds, *.png, *.jpg, *.jpeg, *.tga, *.tif, *.tiff, *.pkm, *.pvr

Property name Default value Description
All common properties, see COvenBakeConfig_Base
AlsoCopyOriginalFile true Will run the command-line, AND copy the original texture to the target path.


For example, a config that calls the DirectX utility texconv on windows to convert all files to dds files, and performs a simple copy on linux/mac, would look like: 

COvenBakeConfig_Texture	$LOCAL$/Texture
{
	CommandLine_Windows = " \"\"%DXSDK_DIR%\\Utilities\\bin\\x86\\texconv.exe\" -o \"$(TargetDir)\" \"$(InputPath)\"\"";
	CommandLine_Linux = "cp \"$(InputPath)\" \"$(TargetPath)\"";
	CommandLine_MacOsX = "cp \"$(InputPath)\" \"$(TargetPath)\"";
}


COvenBakeConfig_TextureAtlas

Used for texture atlas resources.
Applied to: *.pkat

Property name Default value Description
All common properties, see COvenBakeConfig_Base
TrimTexture false If enabled, will store trimming data
TrimBlendedFrames true If enabled, will generate a second set of data generated from a blend of each frame and the next frame. Needed for correct rendering when frame-blending is enabled.
TrimmerVertexCount 8 Number of trimmed vertices to produce for each frame, or for the whole image if no atlas file exists.
TrimmerThreshold 0 Texel value [0-255] below which a texel is considered not significant enough and is discarded by the trimmer.
TrimmerOptimization Hybrid Optimization mode:
  • Relaxation : VERY FAST, good quality results : Iteratively simplifies the trimmed hull.
  • Bruteforce : VERY SLOW, best possible hull : Tries all combinations of simplifications for the target vertex count, keeps the best one.
  • Hybrid : Will try to keep running time as low as possible, while outputting the best quality cutouts it can.
TrimmerOptimizationSearchLimit 160000 Number of possible hull permutations below which the 'Hybrid' method should use bruteforce. when the domain space is larger than this number, will switch a monte-carlo sampling algorithm limited to this number of iteration, then also run the relaxation algorithm, and pick the best result.

Higher numbers has more chance to converge to the best result, but require more time to compute.

TrimmerMaskRGBA 255, 255, 255, 255 Color channel mask to be applied when filtering the image texels before trimming.


COvenBakeConfig_Font

Used when baking fonts into a .pkfm font-metrics file, used by the Text sampler Text sampler to get glyph width and kerning information.
Applied to: *.ttf, *.otf


COvenBakeConfig_HBO

Used for popcorn's generic HBO files.
Applied to: *.hbo, *.pkan, *.pksa

Property name Default value Description
All common properties, see COvenBakeConfig_Base
BakeMode LeaveAsIs Can be any of the following:
  1. LeaveAsIs : performs a straight copy from the source to the target pack without changing anything
  2. Text : forces conversion to text format
  3. Binary : forces conversion to binary format
Endianness LittleEndian Only used when 'BakeMode' is set to 'Binary'. Can be any of the following:
  1. LittleEndian : writes the binary HBO file to little-endian format (native format for PC / PS4 / Xbox-One)
  2. BigEndian : writes the binary HBO file to big-endian format (native format for X360 / PS3 / PS-Vita / ARM / etc...)

Note that if the endianness does not match the target platform, the runtime will still be able to load the files, but will take a bit more time in order to swap all the values to the platform's format.

RemoveEditorNodes true If set to true, will remove all nodes UNKNOWN by the asset-baker (Usually editor-specific nodes).

Care must be taken with custom nodes, as currently this will remove all of them. (will be addressed in the future)

ExtensionsRemap "fbx=pkmm" Array of extensions remaps. The baker will replace the extensions in all file-paths in the currently baked file.

For example, here's how you would remap source .fbx paths to .pkmm, and .png + .tga to a .dds runtime format, if you've setup the texture ovens to convert all pngs and tgas to dds:

ExtensionsRemap =
{
    "fbx=pkmm",
    "png=dds",
    "tga=dds"
};


COvenBakeConfig_Particle

Used for PopcornFX's Particle effect files. Inherits from 'COvenBakeConfig_HBO', and all its properties
Applied to: *.pkfx

Property name Default value Description
All common properties, see COvenBakeConfig_Base
All properties of COvenBakeConfig_HBO
EnableScriptCache true If enabled, will pre-compile scripts and store the compiled IR in the effect file. This will produce faster loading times, as the runtime won't have to recompile scripts when loading ingame.
RemoveInactiveNodes true If enabled, will remove all nodes that are inactive in the effect (for example, inactive evolvers).
RemoveSource true If enabled, will remove the source of all scripts from the baked effect file. Should be used in combination with the 'EnableScriptCache'. When active, will silently enable 'EnableScriptCache', as the effects won't be able to load if the source is removed AND the cache isn't saved.


COvenBakeConfig_Mesh

Used for mesh resources.
Applied to: *.fbx, *.pkmm

Property name Default value Description
All common properties, see COvenBakeConfig_Base
Scale LeaveAsIs Global import scale.

For example, if your mesh has been exported in centimeters, but your project is in meters, set this to 0.01

Endianness LittleEndian Can be any of the following:
  1. LittleEndian : Internal, reserved for future use
  2. BigEndian : Internal, reserved for future use
Geometry
ImportGeometry true If disabled, will not build any geometry (usually disabled for FBX that only contain an animation path and no geom).
GeometryCompression None Determines if geometry should be compressed.
  1. None
  2. FastLZ
  3. BZip
Positions F32 Vertex-format in which vertex positions should be stored.
  1. F32 : 32-bit floating point XYZ components
  2. U16 : 16-bit integer XYZ components, quantized on the mesh bounding box
Normals F32 Vertex-format in which vertex normals should be stored.
  1. None : Do not import normals
  2. F16 : 16-bit floating point XYZ components
  3. F32 : 32-bit floating point XYZ components
Tangents F32 Vertex-format in which vertex tangents should be stored.
  1. None : Do not import tangents, runtime will auto-regenerate them if necessary
  2. F16 : 16-bit floating point XYZ components
  3. F32 : 32-bit floating point XYZ components
Texcoords F32 Vertex-format in which vertex UV coordinates should be stored.
  1. None : Do not import UVs
  2. F32 : 32-bit floating point UV components
  3. U16 : 16-bit integer point UV components, quantized in the [0,1] range
UseTriangleStrips false If disabled, will import triangle indices as regular 3-indices per triangle.

If enabled, will generate triangle strips for the whole mesh.

RebuildNormals false If enabled, will ignore the normals stored in the original mesh, and rebuild them from scratch using mesh geometry.
Animation
ImportAnimation false If enabled, will import animations.
ImportSkeleton false If enabled, will import the skeleton (required for skeletal animations).
UseAnimFrameBind false Define the bind pose as the first frame of the animation.
OptimizeForCPUSkinning false Enable this for faster CPU skinning. Will reorder vertices in the mesh.

Do not check this if you expect the vertices to be in a precise order.

MaxBonesPerVertex 8 Min=1, Max=256.

Maximum number of bones per vertex.

BoneWeightDiscardTreshold 0.0f Treshold below which vertex bone weights will be discarded and set to zero.
RemapToZero true Enable this to avoid your animation offset and make it start at zero.
Kd-Tree
WriteKdTree true If disabled, will not build the KdTree.

Note: if you don't build the KdTree, you won't be able to use some specific features such as ray intersections or projection on this mesh.

KdTree_Compression FastLZ Controls how the KdTree gets compressed.
  1. None : No compression
  2. FastLZ : Use the FastLZ Algorithm (you must make sure the runtime SDK your company has licensed contains the FastLZ decompressor)
  3. BZip : Use the BZ2 Algorithm (you must make sure the runtime SDK your company has licensed contains the BZ2 decompressor)
KdTree_FastBuild false If enabled, will use a much simpler, lower quality, and faster KdTree construction algorithm.
KdTree_MaxNodeVerticesBeforeSplit 15 (Advanced) Maximum number of vertices a node is allowed to contain before being subdivided.
KdTree_MaxDepth 32 (Advanced) Maximum depth the KdTree branches are allowed to reach.
KdTree_MinNodeExtent 1.0e-6f (Advanced) Smallest node size before no more splits happen.
KdTree_NodeTraversalCost 0.1f (Advanced) Heuristic weight : abstract cost of traversing a node at runtime.
KdTree_TriangleIntersectionCost 1.0f (Advanced) Heuristic weight : abstract cost of processing a mesh triangle at runtime.


COvenBakeConfig_StraightCopy

Used for any resource that needs to be packaged to the output resource packs, but does not need/support baking.
Applied to: *.mp3, *.wav, *.txt

Property name Default value Description
All common properties, see COvenBakeConfig_Base


Overriding bake configs

Each oven configuration has a property "BakeTarget". When "BakeTarget" is empty, the config will be applied to ALL configurations, and overridden by configs with explicit bake targets.

For example, if the Config/AssetBaker.pkcf file has the following contents: 

COvenBakeConfig_Particle	$LOCAL$/Particle
{
	BakeMode = Binary;
}
COvenBakeConfig_Particle	$LOCAL$/Particle_x32
{
	BakeTarget = "x32";
	BakeMode = Text;
}
COvenBakeConfig_Particle	$LOCAL$/Particle_x64
{
	BakeTarget = "x64";
	BakeMode = LeaveAsIs;
}

Then the Particle build ovens on ALL build targets EXCEPT "x32" and "x64" will bake particle-effect files in "Binary" mode.
when baking for the "x32" target, effect files will be baked in "Text" mode.
when baking for the "x64" target, effect files will be baked in "LeaveAsIs" mode, which basically tells the asset baker to copy/paste the effect file from the source pack to the x64 target pack, without changing anything.

Retrieved from "https://wiki.popcornfx.com/index.php?title=AssetBaker_1120&oldid=6640"