AssetBaker 170

From PopcornFX
Revision as of 10:52, 29 August 2017 by Jordan (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

See also : Editor interface overview.

This page is for version v1.7.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="dependencies.txt" -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="dependencies.txt"
    • asks to bake the source pack's "dependencies.txt" file (straight copy)
  10. -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="dependencies.txt" -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="dependencies.txt" -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="dependencies.txt" -i="LastRevision.txt"
pause


Important note on runtime popcorn meshes

The Popcorn editor expects to find FBX files in its "Meshes" directory. You might have noticed when browsing for a mesh it writes in the target object properties the path to an .pkmm file, NOT to a .fbx file.
This is because the runtime expects an '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. Therefore, it creates pkmm files in "Cache/Meshes/" at the root of the pack.
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 in "%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.hcf 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_Texture

Used for texture resources.
Applied to: *.dds, *.png, *.jpg, *.jpeg, *.tga


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_Windows <empty> Command-line executed when the baker is run on a windows OS
CommandLine_Linux <empty> Command-line executed when the baker is run on a linux OS
CommandLine_MacOsX <empty> Command-line executed when the baker is run on a MacOsX OS
AlsoCopyOriginalFile true Will run the command-line, AND copy the original texture to the target path.


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


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)\"";
}

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)


COvenBakeConfig_HBO

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

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
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)


COvenBakeConfig_Particle

Used for popcorn's Particle-FX HBO files. (currently identical to COvenBakeConfig_HBO)
Applied to: *.pkfx

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
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 PKFX file to little-endian format (native format for PC / PS4 / Xbox-One)
  2. BigEndian : writes the binary PKFX 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)


COvenBakeConfig_Mesh

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

Not yet documented, subject to potentially heavy changes

  • BakeTarget
  • ResourcePath
  • SourceMeshPath
  • AnimationPath
  • MaterialProxyPath
  • MeshPath
  • ModelPath
  • LevelPath
  • EntityPath
  • TexturePath
  • OutputPkmmPath
  • AxisSystem
  • GenerateAssets
  • TexturesFolderPaths
  • Scale
  • ExcludeNodes
  • CollisionObjects
  • ImportAsSceneGraph
  • Geometry
  • GeometryCompression
  • Vertices
  • Normals
  • Tangents
  • Texcoords
  • CustomStreams
  • Skinning
  • BlendShapes
  • BoundarySmooth
  • BoundaryAutoDetect
  • VertexSewingThreshold
  • Animation
  • Skeleton
  • WriteKdTree
  • KdTree_Compression
  • KdTree_FastBuild
  • KdTree_MaxNodeVerticesBeforeSplit
  • KdTree_MaxDepth
  • KdTree_MinNodeExtent
  • KdTree_NodeTraversalCost
  • KdTree_TriangleIntersectionCost


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
BakeTarget <empty> string, contains the name of the build target this config applies to. an empty string means all build targets


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.hcf 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.