Difference between revisions of "Assets.txt"

Revision as of 23:38, 20 June 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.

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
}

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