This document is intended as a technical reference for the JkGfxMod material compiler. This document assumes the reader is familiar with Jedi Knight: Dark Forces II assets and authoring materials using modern pipelines.
JkGfxMod extends Jedi Knight: Dark Forces II to support high-quality textures. This is accomplished by intercepting the original 8-bit textures as they are loaded, and automatically replacing them with corresponding user-defined materials. The mapping between 8-bit texture data and replacement materials is generated by an offline compile step, using the original textures and colormaps. The output of this compiler is a complete material pack that can be distributed to end users.
The JkGfxMod material compiler, compiler.exe, is a command line utility that assembles a finished material packs from user-supplied definition files and source textures. The material compiler requires original game files to generate embedded metadata that JkGfxMod requires to accurately inject the correct material for each texture.
compile.exe --script <definition file>
--output <target directory>
--resource <JK resource directory>
[optional arguments]
Usage: --script <definition file>
This command line argument is required.
The --script argument specifies the path to a material pack definition file. Please see below for a detailed description of the material pack definition file.
Usage: --output <target directory>
This command line argument is required.
The --output argument specifies the directory where the compiler should assemble the finished material pack. The compiler will create this directory if it does not exist.
Note: The compiler will not clean up this directory between invocations.. Please ensure this directory does not contain errant textures or other files prior to distribution. Manually deleting the output directory prior to a final build is recommended.
Usage: --resource <JK resource directory>
This command line argument is required.
The --resource argument specifies the location of the Jedi Knight: Dark Forces II resource directory. This directory is searched for 8-bit textures and colormaps during the compile process.
Usage: --game <JK mod directory>
This command line argument is optional.
The --game argument specifies the location of Jedi Knight: Dark Forces II user-created content. This argument is roughly equivalent to jk.exe -path <JK mod directory>. The specified directory is searched for 8-bit textures and colormaps during the compile process. Textures and colormaps in this directory override homonymous textures and colormaps in resources.
Usage: --episode <GOB file>
This command line argument is optional.
The --episode argument specifies the location of a Jedi Knight: Dark Forces II GOB file. Typically, this argument will be used if the material pack is intended to replace custom textures contained in an episode GOB. The specified GOB is searched for 8-bit textures and colormaps during the compile process. Textures and colormaps in this directory override homonymous textures and colormaps in both resources and the game directory, if specified.
Usage: set JKGM_LOG_FILE=<log filename>
The JKGM_LOG_FILE environment specifies a file where the compiler will write detailed diagnostic information. This log file is useful for reporting bugs in the compiler.
The material definition file is a JSON document which describes desired materials and replacements. This definition file is passed to the compiler using the --script command line argument.
Example format:
{
"name": "Title of my project",
"description": "A one-sentence description of my texture pack",
"comment": "Miscellaneous or detailed comments descripting the texture pack, such as technical information, license, or author biographical information",
"materials": [
{ ... },
{ ... },
...
]
}
The name field is mandatory. The name field must contain the name of your material pack. Like all titles, material pack names should be brief but recognizable, and should attempt to be as unique as possible.
This field is not currently displayed to the user. Future material pack management software will require this field, if such software becomes necessary.
The description field is mandatory. The description field should contain a brief description of the material pack. In particular, the description field should explain what the material pack does to the game, or if it is intended to inject textures into a specific level or modification, the description field should identify that level or modification.
This field is not currently displayed to the user. Future material pack management software would make use of this field to inform the user, if such software becomes necessary.
The comment field is optional. This field is intended for arbitrary long-form text, such as detailed technical information about the material pack or author information.
This field is not currently displayed to the user. Future material pack management software could make use if this field to display detailed information about installed material packs to the user, if such software becomes necessary.
The materials field lists the materials that will be included in this material pack.
{
"name": "some_unique_material_name",
"replaces": [
"3do/mat/some_mat_to_replace.mat",
[ "mat/animated_mat.mat", 3 ],
[ "mat/animated_mat.mat", 6 ]
],
...
material parameters
...
}
The material name field is mandatory. Each material must have a unique name within its material pack. The name is used to uniquely identify this material, printed for diagnostic purposes, and is used to give unique names for files in the output directory.
The name is case-insensitive, and cannot contain any of the following characters: <>:"/\|?*.
The replaces field is mandatory. This field specifies a list of 8-bit textures that should be replaced by this material. The compiler must be able to read each specified 8-bit texture among the data directories specified on the command line, and will otherwise fail with an error message.
Replacements can have one of the following formats:
Example:
"replaces": [
"mat/some_texture_name.mat"
]
Basic replacements are a brief shorthand for the most common texture replacement case. This replacement instructs the compiler to substitute this material for cel 0 of mat/some_texture_name.mat. Other cels are not replaced.
Example:
"replaces": [
[ "mat/some_animated_texture.mat", 8 ]
]
Multicel replacements encode texture replacements as a tuple of material name and cel number. This replacement instructs the compiler to substitute this material for cel 8 of mat/some_animated_texture.mat. Other cels are not replaced.
Each material object may contain a list of material parameters. The material compiler supports the following fields. Other fields are ignored.
The albedo_map field is optional.
The albedo_map field references a texture with alpha channel. The RGB channels describe the diffuse reflectance of the material in the sRGB colorspace, while the A channel describes linear relative transparency.
If albedo_map is unspecified, the albedo_factor field is used to determine diffuse reflectance.
The albedo_factor field is optional.
The albedo_factor field contains a floating point RGBA vector (array of 4 JSON numbers). If an albedo map has been specified, this vector is component-wise multiplied with the value of the albedo map. If an albedo map has not been specified, the material diffuse reflectance is equal to the albedo factor.
If albedo_factor is unspecified, the material behaves as if albedo_factor were solid white (RGBA all 1.0).
The emissive_map field is optional.
The emissive_map field references a texture. Together with the emissive factor, the RGB channels of this texture describe the emissivity of the material in the sRGB colorspace.
If emissive_map is unspecified, the material emissivity is determined by the emissive_factor field alone.
The emissive_factor field is optional.
The emissive_factor field contains a floating point RGB vector (array of 3 JSON numbers). If an emissive map has been specified, this vector is component-wise multiplied with the value of the emissive map. If an emissive map has not been specified, the material emissivity is made equal to the emissive factor.
If emissive_factor is unspecified, the material behaves as if emissive_factor were black (RGB all 0.0). Note that materials which specify an emissive map must also specify a non-zero emissive factor in order for the material to emit light.
The displacement_map field is optional.
The displacement_map field references a texture. The R channel of this texture describes the depth of the material in a linear colorspace. The other channels of this texture, if they exist, are ignored.
If displacement_map is specified, the material depth is treated as 0 and interpreted normally.
The displacement_factor field is optional.
The displacement_factor field contains a single floating point value. If a displacement map has been specified, this value is used to scale the value of the displacement map for parallax mapping. Positive displacement factors will cause material features to appear to extend out from the face, while negative displacement factors will cause material features to extend into the face. A negative displacement factor is almost always what you want. This value has no suggested physical interpretation, and should be manually adjusted until the desired appearance is achieved.
If displacement_factor is unspecified or is set to 0, parallax mapping is disabled.
Note that parallax mapping is a user-configurable option. Since users may choose to disable parallax mapping, either for performance or aesthetic reasons, your materials should be designed to look acceptable without parallax mapping.
The alpha_mode field is optional.
The alpha_mode field describes how the material should interpret the albedo map alpha channel. If the alpha_mode is blend, the alpha channel is used for alpha blending. If the alpha_mode is mask, the alpha channel is used for alpha testing with a cutoff defined by alpha_cutoff. The default value is blend.
Note that only the albedo map alpha value is considered under the alpha mode. Materials that use the mask alpha mode can be applied to faces flagged translucent, and will render as Jedi Knight: Dark Forces II modders typically expect.
Note also that the alpha mode only applies to translucent faces or faces which normally permit color keyed transparency. The material is drawn opaque on all other faces, with blending and alpha testing disabled.
The alpha_cutoff field is optional.
The alpha_cutoff field describes how the material should interpret the alpha channel when the alpha mode is set to mask. Fragments with an albedo map alpha less than alpha_cutoff are discarded. The rest of the albedo map is considered solid.