Design Note parameters

Since Dark Engine script modules cannot create their own special properties, custom scripts are instead configured with “parameters” stored in the Editor→Design Note property. These parameters have a similar syntax across the various custom script modules (Public Scripts, tnhScript, NVScript, TWScript, and KDScript). Since there are some differences, however, the KDScript parameter syntax is documented here.

In KDScript, an object inherits Design Note parameter values individually from its metaproperties, archetype, and ancestors. For example, if a parameter is set on an object's distant parent archetype and not set on any lower archetypes or the concrete object itself, the object will inherit that parameter regardless of which parents have Design Notes of their own.

Further, Design Note parameters in KDScript may be changed during the course of the mission. Wherever possible, KDScript scripts will use the new values from then on.

General syntax

The Design Note property is a string; it is separated into individual parameters with semicolons (;). Each parameter consists of:

a parameter name
such as renewable_threshold,
a difficulty index
(optional) such as [1,2],
an equals sign
a value
such as 3.

Whitespace (spaces, tabs, line breaks) may appear between parameters and between parts of parameters, and will be ignored. Parameter names are not case-sensitive. The value may be surrounded by single ('') or double ("") quotation marks, and must be quoted if it is to include any semicolons or quotation marks itself. Backslashes, single quotes, and double quotes should be preceded by a backslash (i.e. \\, \', and \"). Here is an example of a longer Design Note:

renewable_threshold[0] = 6; renewable_threshold [1,2]=3  ; renewable_physical=true; transition=30s; curve=quadratic; precip_freq_on=100.5;precip_wind_on=10,-2.5,0; fog_color_on=#c862a3; message =   "  He called me a \"taffer\"!"

Difficulty variation

In KDScript, all parameter values may vary based on the player's chosen difficulty level. Any of the difficulty indexes below may appear between square brackets ([]) after any parameter name. The following value will only be used if the difficulty matches. If a parameter appears more than once in a Design Note, the last value for the parameter with a matching difficulty will be used. See the example Design Note above for an example.

0, n, or normal
Normal difficulty, such as renewable_threshold[0]=6
1, h, or hard
Hard difficulty, such as renewable_threshold[1]=4
2, e, or expert
Expert difficulty, such as renewable_threshold[2]=2
0,1, 0-1, or n,h
Normal or Hard difficulty, such as inert_until_dropped[0,1]=false
1,2, 1-2, or h,e
Hard or Expert difficulty, such as drop_on_alert[1,2]=false
0,1,2, 0-2, n,h,e, any
any difficulty (default if no index given)

Value types

Each parameter has one of the types described below. Its value must be formatted accordingly. Types marked with an asterisk (*) can be set via a quest variable; to do this, set the parameter value to a dollar sign ($) followed by the quest variable name, for example renewable_threshold=$max_arrows.

boolean *
A true-or-false value, where values starting with T, t, Y, or y are true, numeric values other than zero are true, and all other values are false. Examples: true, 1, yes; false, 0, no.
integer *
A number without any fractional or decimal part, whether positive, negative, or zero, such as 6128 or -73.
object *
real *
A number with an optional fractional or decimal part, such as 82.34, -16, or 0.4.
Text of any kind, such as "Besie something?" or obj\txt16\bottle1. Quotation marks around the text are recommended if the text has spaces or special characters in it (see the rules above).
time *
A triplet of three real numbers separated by commas, usually XYZ coordinates, such as -10.0,2.5,4.0.
This documentation is part of the KDScript module. Copyright © 2012–2013 Kevin Daughtridge. See introduction for details.