Assets.txt

From KK's Wiki
Revision as of 01:41, 29 December 2020 by Krzysiek (Talk | contribs)

Jump to: navigation, search

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


Contents

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. Names like A or B are only examples. Any version names can be used, but single letter ones are best to fit in the application UI. 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 [$rgb_out] (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.

Optionally, the $rgb color can be followed by another color value in the same format, which be used as output color for preview rendering and export. In normal case, where there is only one, it's used both for import and export.


-ramp <index1> <index2> ...

Specifies a color ramp to be used for dithering. This option should be specified before any -weight option. The first occurrence of -ramp and disallows dithering from using any color pair except when such colors are consecutive colors in the ramp. Further ramps can enable additional color pairs.


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


-masterbrightness <value>

Sets the brightness level for all the assets imported using this palette. This effect is applied on top of any other effects applied during import.


-colorspace <mode> [{ ... ]

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

  • rgb - standard RGB space (sRGB)
  • xyz - XYZ color space
  • yuv - YUV color space
  • lab - CIE Lab color space
  • badlab - old broken implementation of the CIE Lab color space, which sometimes gave better results


The colorspace block accepts following options:

  • -weights
  • -gamma
  • -luma


-weights <w1> <w2> <w3> [<w4>]

This option specifies per-channel weights for each component of the selected color space ('R/G/B, Y/U/V, X/Y/Z or L/a/b). E.g. a weight equal 0 means that the component should be ignored, where 1 means the default contribution. Additionally, the RGB color space introduces an optional 4th component of luminance.


-gamma <gr> [<gg> <gb>]

( RGB colorspace only )

Specifies gamma value (per-channel, optionally) of the color space. E.g. using gamma value between 2.0 and 2.4 should make the RGB color space more or less linear.


-luma <wr> <wg> <wb>

( RGB colorspace only )

Specifies per-channel weights for color luminance estimation. The weights are automatically normalized internally. If luminance error weight was not set (e.g. no -weights option was specified), the luminance weight is now set to 1.0.


-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
  • y_checker - produces pattern by using sort or rev_sort method depending on pixel row
  • 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
  • -loop
  • -walkswing
  • 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.


-loop

Places loop point in the animation. When animation is finished, playback restarts from this point. If loop point is missing, entire animation loops by default.

To make the animation stay on the last frame place -loop point just before the last frame, preferably making the frame longer to save CPU power on frame switching logic.

The loop point is currently an engine-only feature and DreadTool always repeats entire animation.


-walkswing [<0/1>]

Enables or disables weapon swinging for frames following this definition. Every animation definition starts with walk swing disabled by default.

If the argument is missing, it turns this option on.

The weapon swing simulation is currently an engine-only feature and DreadTool doesn't simulate the weapon swinging.


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.


Generic asset options

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


-visualscale <scale> [<yscale>]

Provides visual scaling information used in the preview mode (most notably, for sizing the sprites). The <scale> is a real number scale factor (1.0 means no scaling, i.e. original file resolution is used). If <yscale> is not specified, the same scale is applied to both axes.


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


-export [ <mode> ] ...

Forces the asset to be exported in the specified format, even if the resource is not hardcoded and has no references from usage in the project. Useful for exporting additional graphics (e.g. menus) without hardcoding the names into the tool.

Available <mode> keywords. Any number of them can be specified:

  • off - do not export (for overriding the settings of the parent group)
  • bitplane - export as bitplanes, one after another, ending with mask bitplane (if graphics is masked)
  • bitplane_interleaved - export as line-interleaved bitplanes (option recognized, but not implemented)
  • bitplane_st - export as word-interleaved bitplanes (ST memory ordering, option recognized, but not implemented)
  • header - include simple header before the data (width, height, stride in bytes - one word each)
  • noheader - disable the above (for overriding parent group)
  • font_mask - export ALL graphics of this asset group as 1bpp font with special header containing font information
  • 0bpp - export no color bitplanes (e.g. mask only for masked graphics)
  • 1bpp - export color as 1 bitplane, with optional mask
  • 2bpp - export color as 2 bitplanes, with optional mask
  • 3bpp - export color as 3 bitplanes, with optional mask
  • 4bpp - export color as 4 bitplanes, with optional mask
  • 5bpp - export color as 5 bitplanes, with optional mask
  • 6bpp - export color as 6 bitplanes, with optional mask


-export_amiga [ <mode> ] ...

Similar to -export, but provides export only for the Amiga platform.


-export_st [ <mode> ] ...

Similar to -export, but provides export only for the ST platform.


Graphics asset processing options

Graphics processing sequence

The following options control operations performed on each loaded graphics asset. The operations are performed in order of appearance on the list below.

The processing operation sequence is:

  • Color keying (-colorkey)
  • Scroll (-scroll)
  • Downscaling (-downscale / -collapse / -lanczos)
  • Color adjustsments (-gamma / -gain / -lift / -lightlevel / -masterbrightness)
  • Dithering (-palette / -autopal)
  • HD packing (-downscale HD / -lanczos pack)
  • Trimming (-trim)


-colorkey <color> [<mask>]

The asset is preprocessed 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.


-scroll <dx> <dy>

Scrolls (moves) the image pixels by specified offset. Image is wrapped across borders - pixels leaving one side, return from another.


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

This option downscales affected assets during import. The only supported <ratio> values are:

  • -downscale 0 - downscaling disabled
  • -downscale 2 - scale image down by 50% by averaging 2x2 groups of pixels
  • -downscale 1 2 - scale image down only vertically by 50% by averaging vertical 1x2 pairs of pixels
  • -downscale 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 and -lanczos. 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 and -lanczos - the latest specified option overrides previous ones.


-lanczos <x0> <y0> <xstep> [<ystep>] [blur <bx> [<by>]] [width <wx> [<wy>]] [pack]

Performs Lanczos downsampling of the image. This should allow quick asset prototyping by drawing the high resolution sketch of the art instead of pixeling it. The <x0> and <y0> specify the origin location coordinates on the high resolution image, which location after downscaling will be used as the final image origin. To produce downscaled image, the high resolution image is sampled in a grid pattern (each grid point produces one pixel of the final image). Samples are taken with steps specified by <xstep> and <ystep> (if the latter is missing, the grid is uniform). The sampling area is not specified directly and covers entire source image. The grid step values must be integer - fractional scaling is not supported now.

For best results, the Lanczos filter blurs the image with blur size equal to the grid step. This can be overridden by specifying blur <bx> <by> option, which provides the blur size in both directions (specifying only one makes the blur uniform). Blur size is specified in pixels of the high resolution (source) image. Fractional blur sizes are supported. Specifying blur 0 will reduce the Lanczos filter to point filter (a.k.a. no filtering / nearest neighbor).

The Lanczos filtering kernel size can also be controlled by the width <wx> <wy> option. The kernel size defaults to 3x the blur size (separately in each direction), which is also known as the Lanczos3 downsampling kernel. The width <wx> <wy> option can override this setting (although this will be probably used very rarely). Fractional values are supported.

The final pack option turns on the horizontal pixel packing (performed after the dithering), similar to the -downsacle HD option. In such case, the specified <xstep> value should usually be equal to half of the <ystep> to maintain the image aspect ratio.


The -lanczos option is mutually exclusive with -downscale and -collapse. The latest specified option overrides previous ones.


-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> [<pathext>]

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

Optionally, a <pathext> name extension can be specified, which is added to the loaded file name for this light level. This allows loading a premade set of textures for light levels.


-nolight

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


-palette <name> [ { ... ]

Specifies palette to dither/map the image to. The palette must already be defined beforehand before specifying this option. 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.

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