Difference between revisions of "Assets.txt"

From KK's Wiki
Jump to: navigation, search
m
Line 43: Line 43:
 
Example:
 
Example:
 
  include "included-file-name.txt"
 
  include "included-file-name.txt"
 +
 +
 +
== Versions (A/B testing) ==
 +
 +
Parts of the file can be marked as conditional to allow faster changing of settings for A/B comparison.
 +
 +
Example:
 +
palette Main {
 +
    $000
 +
    version A {
 +
        $222
 +
        $333
 +
        $555
 +
    }
 +
    version B {
 +
        $111
 +
        $333
 +
        $444
 +
    }
 +
    $777
 +
    ...
 +
}
 +
 +
In the above example version conditions are used to quickly change the gray ramp in the palette.
 +
Adding the ''version'' block causes all used version labels to appear in the tool UI as clickable buttons.
 +
Clicking one of them deselects all other versions and selects/deselects the clicked one.
 +
Alternatively, you can hold down the ''Control'' key to select multiple versions together.
 +
Any change in the UI version buttons causes all the assets to reload with new version settings.
 +
 +
Every version label (e.g. ''A'', ''B''... but any names can be used) is a flag always set to either ''true'' or ''false''.
 +
For A/B testing, normally only one version is set to ''true'' and the rest is set to ''false'', but deselecting and ''Ctrl+click'' allows to specify any flag combination in the tool.
 +
 +
The ''version'' statement in the ''assets.txt'' files is followed by list of version labels, with optional negations, that specify when the version block should be included, and when it shouldn't.
 +
If negated and non-negated flags are mixed, the rightmost flag that has value of ''true'' takes precedence.
 +
 +
Examples:
 +
* ''version A'' - include the block when ''A' is selected
 +
* ''version !A'' - include the block when version ''A'' is NOT selected
 +
* ''version A B C'' - include the block when at least one of ''A'', ''B'' and ''C'' is selected
 +
* ''version !A !B !C'' - include the block when none of ''A'', ''B'' and ''C'' is selected
 +
* ''version !A !B'' - include the block when neither ''A'' nor ''B'' is selected
 +
* ''version A !B'' - if ''B'' is selected (rightmost flag) then ignore the block, otherwise include it if ''A'' is selected
 +
* ''version !B A'' - if ''A'' is selected (rightmost flag) then use the block, otherwise use it if ''B'' is not selected
 +
* ''...''
 +
 +
The ''version'' statement can be used anywhere in the file - in any other block, or at the top level.
 +
The versions selected in the UI are saved upon exit in the ''config.cfg'' file.
  
  

Revision as of 10:34, 10 August 2020

This page is still under construction - much of the infrmation is still to be filled


File Structure

The assets.txt file controls what assets are imported, and how the import process is performed.

The file is a list of definition entries. Using one of the following keywords:

  • palette
  • gfxgroup

Example assets.txt file could have the following structure:

palette Main {
    ... define palette 'Main' here ...
}

palette HUD {
    ... define palette 'HUD' here ...
}

... define other palettes if needed ...

gfxgroup Textures {
    ... specify group contents ...
}

... define other groups and/or palettes ...


Comments

The file accepts both C-style single line comments, and shell-style comments.

 // This is a comment.
 # This is a comment too.


Include

Additional files can be included at any point in the file. Include path is relative to path of the file currently being processed.

Example:

include "included-file-name.txt"


Versions (A/B testing)

Parts of the file can be marked as conditional to allow faster changing of settings for A/B comparison.

Example:

palette Main {
    $000
    version A {
        $222
        $333
        $555
    }
    version B {
        $111
        $333
        $444
    }
    $777
    ...
}

In the above example version conditions are used to quickly change the gray ramp in the palette. Adding the version block causes all used version labels to appear in the tool UI as clickable buttons. Clicking one of them deselects all other versions and selects/deselects the clicked one. Alternatively, you can hold down the Control key to select multiple versions together. Any change in the UI version buttons causes all the assets to reload with new version settings.

Every version label (e.g. A, B... but any names can be used) is a flag always set to either true or false. For A/B testing, normally only one version is set to true and the rest is set to false, but deselecting and Ctrl+click allows to specify any flag combination in the tool.

The version statement in the assets.txt files is followed by list of version labels, with optional negations, that specify when the version block should be included, and when it shouldn't. If negated and non-negated flags are mixed, the rightmost flag that has value of true takes precedence.

Examples:

  • version A - include the block when A' is selected
  • version !A - include the block when version A is NOT selected
  • version A B C - include the block when at least one of A, B and C is selected
  • version !A !B !C - include the block when none of A, B and C is selected
  • version !A !B - include the block when neither A nor B is selected
  • version A !B - if B is selected (rightmost flag) then ignore the block, otherwise include it if A is selected
  • version !B A - if A is selected (rightmost flag) then use the block, otherwise use it if B is not selected
  • ...

The version statement can be used anywhere in the file - in any other block, or at the top level. The versions selected in the UI are saved upon exit in the config.cfg file.


Palette definition

A palette is defined by specifying color values and dithering options. Palette is defined at the top level of the assets.txt file, within other palettes or special options (described later). Every palette has a name, allowing it to be referenced. Palette names must be unique.

Use the following syntax.

palette NameOfMyPalette {
    // place colors, dithering options and sub-palettes here
}


$rgb (color definition)

A dollar sign $ within palette definition adds one color to the palette. 3 hex digits specify the value of red, green and blue components, 4 bits per component (Amiga OCS precision).

Example:

    $000		//	black
    $222		//	gray ramp
    $333		//	|
    $555		//	|
    $777		//	|
    $BBB		//	|
    $FFF		//	white
    $343		//	green ramp
    $573		//	|
    $774		//	|
    $004		//	blue
    $320		//	brown
    $431		//	brown
    $CA5		//	yellow
    $C00		//	red
    $600		//	|

Comments are optional, but help.


-weight <color1> <color2> <weight>

Allows to modify likelihood, with which given color pair will be used. Color order does not matter. <color2> can be replaced with * to affect all color combinations with <color1>. <weight> equal 0 disables given combination.

    -weight 13 15 0.5    // reduce usage of yellow-darkred pair (according to the palette above)
    -weight 14  *  0     // don't use bright red at all


-mainpal

Sets the palette as the main palette to be used for rendering 3D world.


-hudpal

Sets the palette as the main palette to be used for HUD drawing (a.k.a. the status bar).


-colorspace <mode>

Specifies the color space in which conversion and dithering error will be computed. Possible <mode> values are:

  • rgb - standard RGB space
  • lab - CIE Lab color space


-dither <mode>

Selects the dithering algorithm. Possible <mode> values are:

  • solid - best color is chosen to use for entire logical pixel ("vertical" dithering disabled)
  • full - all color pairs are checked and best pair is used for the logical pixel (full "vertical" dithering)
  • half_closest - one color is chosen closest to the target color (ignoring error diffusion), the the second color is picked (with error diffusion) to make best color pair
  • checker - similar to full, but a 2x2 logic pixel block is used, as well as vertical dithering to produce 3 intermediate colors for each color pair
  • checker_closest - similar to checker, but one of the colors is picked for closest, undithered match (as in half_closest method)


-pairorder <mode>

Selects the order in which colors are placed when coloring logic pixel halves separately ("vertical" dithering). Possible <mode> values are:

  • keep - keep the order produced by the dithering method (useful with checker and checker_closest)
  • sort - colors are placed in order of their index in the palette
  • rev_sort - similar to sort, but the order is reversed
  • checker - produces checkerboard pattern by using sort or rev_sort method depending on pixel position
  • solid_checker - produces solid pixel checkerboard pattern by picking alternatively one or the other half of the logic pixel

-mixpenalty <weight> [<wr> <wg> <wb>]

When dithering algorithm considers using a color pair instead of a solid color, this option adds error proportional to <weight> and difference of the two colors considered. Optionally, per-component weights can be specified controlling influence of the mixing. In case of the CIELab color space, the weights will be for L, a and b.


-errordiffuse <right> <downleft> <down> <downright>

Enables dithering error diffusion. When final color is computed (or average of two color halves of logical pixel), its difference from ideal color is computed and error is spread to neighboring pixels not yet processed. This causes these pixels to partially compensate for the error, or spread the error further accumulating until correction is done. All specified weights should be zero or greater and sum up to 1 or less.


-diffuseweights <wr> <wg> <wb>

Applies extra per-component weights to the error diffusion. In case of the CIELab color space, the weights will be for L, a and b.


palette <name> { ...

You can define a palette inside another palette, using new, unique palette name. The derived palette will initially have all colors and options of the parent palette copied, which could be then further changed. You can also add new colors to the palette.

This sub-palette specification is most useful, when you want to keep the colors of the palette, but specify different dithering options for some assets. For example:

palette Main {
	-mainpal
	-dither half_closest
	-pairorder sort
	-errordiffuse 0.328 0.141 0.234 0.047

	$000		//	black
	$222		//	gray ramp
	$333		//	|
	$555		//	|
	$777		//	|
	$BBB		//	|
	$FFF		//	white
	$343		//	green ramp
	$573		//	|
	$774		//	|
	$004		//	blue
	$320		//	brown
	$431		//	brown
	$CA5		//	yellow
	$C00		//	red
	$600		//	|

	palette Main_Weapon {
		// reduce spreading of color error, to prevent red dithering spots on weapon hands
		-diffuseweights 1.0 0.2 0.2
		-mixpenalty 0.1
	}
}


Asset group definition

Asset group is a virtual "folder" containing similar assets, often sharing same import settings. A palette is defined by specifying color values and dithering options. Asset group is either defined at the top level of the assets.txt file or within other asset groups.

Use the following syntax.

gfxgroup NameOfMyAssetGroup {
    // place options, sub-groups and assets here
}

gfxgroup <name> { ...

Create another sub-group inside this one. The sub-group will inherit all options of the parent group, which can be modified further. This nested grouping will also show in the importer as nested asset categories, which will be useful for browsing the assets.

Example:

gfxgroup Objects {
    gfxgroup Monsters {
        gfxgroup Soldier {
            // place actual assets here
        }
        gfxgroup AnotherMonster {
            // place actual assets here
        }
    }
}


gfx <name> [<xoff> <yoff>] [ { ... ]

Specifies asset within the asset group. The asset name must be globally unique, and will be used both for the asset name and the source file name, so name your files accordingly. You can optionally provide graphics offsets, which will be used to correctly position objects in 3D world or weapon graphics (not used with textures). Optionally, you can also start a new, hidden group, in which this asset will be placed.

Example:

gfxgroup Textures {
    // Options for all textures in this group
    gfx WALL47_1 {
        // Hidden group for this texture only, specifying options for this asset alone.
    }
    gfx RW11_3
    gfx RW23_4
}


anim <name> { ...

Defines animation preview using previously defined frames. Except for special cases, the animation is for preview only and not used in the engine. Animation <name> is used only for description.

Animation block can contain following definitions:

  • -name
  • frame


-name <anim-name> (anim block only)

Assigns reference name to the animation to allow using it from scripts (e.g. for sprite animation). The name must be unique in the project.


frame (anim block only)

Specifies animation frame. Graphics asset <gfx> will be displayed for <time> ticks (one tick = 1/300s). If either or both <gfx> and <time> is replaced with - or * character, time or graphics from previous frame definition are repeated. Optionally, offsets can be specified to move the graphics.


-verbose [<0/1>]

Controls printing additional debug info during import of affected assets. If the argument is missing, it turns this option on.


-path <path>

Specifies path of the directory, from which assets of the group should be imported. The path is relative to the directory of the definition file. If the path contains spaces, it should be enclosed in quotes. But better: don't use paths and names with spaces.


-masked [<0/1>]

Specifies whether transparency masking should be used by assets in this group. If the argument is missing, it turns the masking on. The setting here must match the usage in the engine, e.g. enabling masking for textures won't make textures transparent in game. When masking is turned on, alpha channel of the imported graphics is used - pixels with alpha 127 or lower are transparent.


-colorkey <color> [<mask>]

Enables preprocessing of the asset to convert specific color into transparent regions. Color and optional mask should be specified in the 0xRRGGBB format as a hex number. Alternatively, you can use * in place of <color>, in which case the converter uses the upper-left pixel of each image as its transparent color. If <color> parameter is the word "off", color keying is disabled.

Turning the color key on or off also automatically enables or disables the -masked option.


-trim [<0/1>]

Turns image trimming on or off. If the argument is missing, it trimming is enabled. Trimming causes transparent areas around the image to be cut off and updates asset offsets to maintain the correct position. This might help reducing memory usage and improve performance by limiting the asset only to the required region.


-downscale [<ratio> [<yratio>]]

This option causes affected assets to be downscaled during import. The only supported <ratio> values are:

  • 0 - downscaling disabled
  • 2 - scale image down by 50% by averaging 2x2 groups of pixels
  • 1 2 - scale image down only vertically by 50% by averaging vertical 1x2 pairs of pixels
  • hd - downscale vertically by 50%, then after dithering downscale horizontally by packing pixel pairs into vertical logic pixel halves

Ratio of -2 has currently the same meaning as hd, but is deprecated.

Mutually exclusive with -collapse - the latest specified option overrides previous ones.


-collapse [<0/1>]

Turns on or off collapsing of the asset. When collapsing is on, entire asset image is averaged down to a single pixel. Useful for floor "textures" replaced by a single color. Not useful anywhere else. Mutually exclusive with -downscale - the latest specified option overrides previous ones.


-texture

Marks assets to be used as wall textures in the engine.


-graphics

Marks assets to be used as generic graphics in the engine. E.g. for status bar display.


-flat

Marks assets to be used as solid color for floor. Specifying this option automatically enables the -collapse option.


-weapon

Marks assets to be used as graphics for weapon the player is currently holding.


-weaponsprite

Marks assets to be used as hardware sprite graphics for weapon the player is currently holding.


-object

Marks assets to be used as objects drawn in 3D world.


-palette <name> [ { ... ]

Selects a palette to be used for importing the assets. The palette must already be defined beforehand before specifying this potion. No assets can be imported before a palette is chosen. Optionally, a new palette block can be specified, which creates a new palette based on the specified one, but with possibly new options. If a palette is already loaded (e.g. by a parent asset group), a * can be used for name to use the current palette as a base of the option block.

Example:

gfxgroup TexturesNotDithered {
    -palette Main {
        // Create copy of palette 'Main', disable dithering error diffusion and use it
        -errordiffuse 0 0 0 0
    }
    // specify some assets here
}


-autopal [<base-palette>] <max-colors> [ { ... ]

Creates and uses new palette, optionally copying the <base-palette>. Specify * as <base-palette> to use current palette as the base palette. When assets are imported using this palette, new colors are added to it until it reaches <max-colors>. Palette block for the new palette may follow this definition.

When importing assets with hardware color count limitations (e.g. weapon sprites), make sure to specify <max-colors> above the true hardware limit. This way palette overflow errors can be detected later.


-gamma <gamma> [ <gamma2> <gamma3> ]

Selects the gamma correction value to be applied during import of the asset. If three gamma values are specified, they are used for each component separately, depending on the selected color space.


-gain <gain> [ <gain2> <gain3> ]

Specifies the color multiplier to be applied during import of the asset. If three gain values are specified, they are used for each component separately, depending on the selected color space.


-lift <lift> [ <lift2> <lift3> ]

Specifies the value added to the color during import of the asset. If three lift values are specified, they are used for each component separately, depending on the selected color space.

The gamma/gain/lift operations are applied exactly in this order, with:

  • gamma - using power function with given exponent on each color component
  • gain - multiplying the result by given value, per component
  • lift - adding specified value to each color component

All operations are performed in the chosen color space - RGB or CIELab.


-lightlevel <lightvalue> <gain>

Specifies one light level for the affected assets. <lightvalue> is an integer 0..255 describing light intensity as used in imported WAD file. <gain> is the extra value, that is used when importing an asset at this light level. The <gain> value is used on top of the value specified with -gain option, not replacing it. If any light level is specified for current group, all light levels inherited from the parent group are discarded, so all required light levels must always be specified together. When WAD files are converted, assets from closest specified light level are used (the converter never adds extra light levels by itself).


-nolight

Discards all specified light levels. Assets imported without light levels specified are imported unlit.