Assets.txt

From KK's Wiki
Revision as of 23:22, 20 June 2020 by Krzysiek (Talk | contribs)

Jump to: navigation, search

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

{{toclimit|limit=2}


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.


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


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


-path <path>

Specifies path of the directory, from which assets of the group should be imported. The path is relative to the working directory. 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.


-downscale [<ratio>]

This option causes affected assets to be downscaled during import. The only supported <ratio> is 2, which scales images down by 50% by averaging 2x2 groups of pixels. Mutually exclusive with -collapse - 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.


-sprite

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
}


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