Assets.txt

From KK's Wiki
Revision as of 22:59, 21 October 2020 by Krzysiek (Talk | contribs)

Jump to: navigation, search

This page is still under construction - much of the information 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. 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.


-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
  • 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
  • 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)
  • Trimming (-trim)
  • Downscaling (-downscale / -collapse)
  • Color adjustsments (-gamma / -gain / -lift / -lightlevel / -masterbrightness)
  • Dithering (-palette / -autopal)


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


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


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


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