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.

color

• A hexadecimal RGB color number in #RRGGBB or #RGB format, such as #66ff99 or #a73; or
• a decimal RGB color triplet R,G,B where values range from 0 to 255, such as 255,128,255; or
• one of the following named colors:
  • aqua
  • black
  • blue
  • chartreuse
  • dodger
  • fuchsia
  • gold
  • gray
  • green
  • grey
  • lawn
  • lime
  • maroon
  • navy
  • olive
  • orange
  • orchid
  • pink
  • purple
  • red
  • rose
  • silver
  • slate
  • spring
  • steel
  • teal
  • turquoise
  • violet
  • white
  • yellow

integer *

A number without any fractional or decimal part, whether positive, negative, or zero, such as 6128 or -73.

object *

• The DromEd name of a concrete object, metaproperty, or archetype (including stimuli, rooms, flow groups, etc.), such as AirCrystal or Player; or
• the number of a concrete object, metaproperty, or archetype, such as -8 or 127.

real *

A number with an optional fractional or decimal part, such as 82.34, -16, or 0.4.

string

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 positive integer number of milliseconds, such as 500 (half a second); or
• a positive real number of seconds followed by s, such as 15s; or
• a positive real number of minutes followed by m, such as 5.2m.

vector

A triplet of three real numbers separated by commas, usually XYZ coordinates, such as -10.0,2.5,4.0.