Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

The resource compiler Using batch processing, the Resource Compiler (RC) is able to batch process all of the asset files for a specific platform in one go , using batch processingonly.

To do this, you invoke the resource compiler RC with the /job switch, where you specify a path to a Job XML file.

For example, to build the main part of the SDK assets as shipped, we use:

...

Table of Contents
maxLevel4
minLevel2
excludeOverview

Job XML

...

Format

The job Job XML format is specified using an XML file, which you can edit in using any Text Editor of your choosing.

...

It is important to understand that a Job XML is a template for a build, which is specialized using parameters passed on the command line. Generally speaking the most important is the 'p' parameter (platform).

During the batch execution each command-line parameter is converted to a property, just like every other RC property.

Tip
For a list of properties used by the RC, run 'rc.exe /help'.

Property values can be accessed inside the Job XML script using the '${propertyname}' construct, which can be used to set other properties, or to conditionally execute parts of the batch.

...

It is possible to pass in a "feature flag" and adjust conversion-properties accordingly (i.e, a property that controls other properties). For this, use a <Properties> XML block block.

In the SDK we can pass a "streaming" property, or if it's not specified we set it according to the platform-property 'p'.

...

Using these constructs, you can write a "subroutine" inside the XML that can be called multiple times with different variables (where the variable values are stored in named properties).
For example:

Code Block
languagexml
<MySubRoutine>
  <!-- Takes parameters "what" and "destination" -->
  <Job Input="${What}" Zip="${Destination}/MySubRoutine.pak" />
</MySubRoutine>

<MainRoutine>
  <!-- Call subroutine for packing *.foo into C:/Some/Path/MySubRoutine.pak -->
  <Run Job="MySubRoutine" What="*.foo" Destination="C:/Some/Path" />
</MainRoutine>

In this example, let's suppose 'MainRoutine' was executed (either using command-line /jobtarget=MainRoutine or a <Run Job="MainRoutine"/> as a child of the root XML for example).
The <Run> tag will be used to "call" the "subroutine" 'MySubRoutine' by name. The attributes What and Destination are specified inline in the example and will be visible inside 'MySubRoutine'.
Once the 'MySubRoutine' "call" has "returned" to the 'MainRoutine', the value of What and Destination will go back to their previous value (if any).

...

Code Block
languagexml
<RCJobs>
  <Foo>
    <Properties A="a" />
    <!-- Do something with A B and C --> 
  </Foo>
  <Bar>
    <DefaultProperties B="b" />
    <Properties A="x" />
    <Run Job="Foo" C="c" />
    <!-- Here, A==x -->
  </Bar>
  <Run Job="Bar" />
</RCJobs>

Suppose Lets suppose you run this example file, the values of A, B and C will be 'a', 'b' and 'c' respectively at the commented line.
The value 'x' of A is passed into Foo, but then overwritten. However, once Foo returns, the value 'x' will be restored.
Also, it would be possible to change the value of B by passing the command-line parameter "/B=x" when running the job to modify from the default behavior.

...

Asset conversion is defined through <Job> XML blocks, and that execute serially (although the sub-parts of some jobs can be executed in parallel , - see the RC property threads).

Jobs iterate over a set of files (in the local file system), thus invoking RC processing for each file in the set and as if the RC was specifically invoked for that file specifically (while using the properties currently set through the batch script for execution).

...

In general, it makes sense to only execute a single conversion type inside a single job block, thus "input" is typically set to a file extension mask, for example: *.tif

Here is an example of how to process textures from CryTiff (*.tif) files to platform-specific files (typically *.dds for PC):

...

Thus, it is sensible to limit the file set to a single filetype and only specify conversion parameters for that specific conversion to keep your Job XML file understandable.

The list List of meaningful conversion parameters for a given conversion can be found by calling 'rc.exe /help'

 

Info
In general, conversion will take into account the relative path from the 'sourceroot' property to the matched file and use the same relative path to store the 'targetfile', but relative to the 'targetroot' property.
Note

Please note that any job that is run with SourceRoot==TargetRoot will not match any files (and thus will do nothing) regardless of actual files.
Since The RC has several transformations that do not change the filename of the source or the target (as this would cause problems.
Even ), and even though there are several transformations that could work, for simplicity this is treated as an error.

...

Sometimes it makes sense to not do any processing for a given set of filefiles.

In that case, you can set the special conversion parameter 'copyonly'  to 1, which will just copy all the files matching the input-set restrictions to that target folder.:

Code Block
languagexml
<CopyJob>
	<Job sourceroot="${source_folder}" input="*.xml" targetroot="${target_folder}" copyonly="1" />
</CopyJob>

...

The input set can be further controlled by the following special properties:

  • recursive: (default is 1).
    When set to 0 the search will only consider files in the 'sourceroot ' folder, but not in subfolders.
  • input: (default is '*').
    Matches the relative path to the specified expression(s) and only passes files that match one or more of the expression(s).
    Use '*' to indicate zero or that more characters are accepted in that location.
    Split multiple expressions using semicolons, '*.a;*.b' will pass all filenames ending with '.a' or '.b'
  • exclude: (default is none).
    Like "input", except any file matching the expression(s) is not passed.
    Exclude overrides "input", so a file matching both expressions will NOT be in the input set.
  • listfile (default is none).
    Opens the specified expression as a text file and restricts the input set to any file in the list.
    The list file is a a text file, with each file on a separate line.
  • exclude_listfile (default is none).
    Like 'listfile' exception, any file matching the list is not passed.
    Exclude overrides 'listfile', so a file in both lists will NOT be in the input set.

...

In that case, you can use the property overwriteextension to force the RC to pick the converter for the overridden extension instead of the convertor i.e rather than the converter it would have picked for the actual extension.

For example, to force a .mtl file to be converted as if they were XML files , you can use:

Code Block
languagexml
<Job input="*.mtl" overwriteextension="xml" ...rest of the job... />

...

Once you have specified all the job groups that you need, you can run them using a <Run> block:

...