23a:Dipscript - Revision history

Quietust at 02:23, 6 February 2025

2025-02-06T02:23:33Z

Quietust at 20:47, 14 April 2014

2014-04-14T20:47:27Z

Quietust: /* Readable variables */ DF Talk #21 describes bits of this

2014-03-31T18:52:52Z

Readable variables: DF Talk #21 describes bits of this

Quietust at 20:08, 30 March 2014

2014-03-30T20:08:34Z

Quietust: /* Script Tokens */

2014-03-30T01:57:43Z

Script Tokens

Quietust: /* Script Tokens */

2014-03-28T20:36:44Z

Script Tokens

Quietust: /* Script Tokens */

2014-03-28T17:27:04Z

Script Tokens

Quietust at 17:24, 28 March 2014

2014-03-28T17:24:23Z

Quietust: Created page with "{{av}} A '''dipscript''', or "diplomat script", is what controls the behavior of visiting diplomats when they meet with your nobles. Dipscripts were originally used t..."

2014-03-28T17:23:21Z

Created page with "{{av}} A '''dipscript''', or "diplomat script", is what controls the behavior of visiting diplomats when they meet with your nobles. Dipscripts were originally used t..."

New page

{{av}}

A '''dipscript''', or "diplomat script", is what controls the behavior of visiting [[diplomat]]s when they meet with your [[noble]]s. Dipscripts were originally used to trigger special events at specific points in the lifetime of one's fortress (such as undead invasions), but much of this was stripped out by the time the first version of Dwarf Fortress was actually released.

Only 5 different dipscripts are ever executed during gameplay, and they are defined in records 13-17 of the game's "index" file: ELVES_FIRSTCONTACT, HUMAN_STANDARD, DWARF_LIAISON, HUMAN_TRADE, and ELVES_STANDARD. The dipscript files themselves are compressed and scrambled, making them difficult to edit (in later versions, they are only compressed).

The following tokens can be specified in a dipscript:
{|
! Token
! Meaning
|-
|INITIAL_LOAD
|Purpose unclear - all dipscripts have this as their second line
|-
|DIPSCRIPT:name
|Specifies the script's name. Must be one of the names defined above if you want the game to ever execute it.
|-
|VAR:type:name
|Declares a variable. Type can either be UNIT or LONG.
|-
|SETVAR:dest_class:dest_name:src_class:src_name
|Sets one variable to another. See below for more information.
|-
|IF:class1:name1:comparison:class2:name2
|Compares the two specified variables and performs the following script steps if the condition is true.
|-
|ELSE
|Performs the following script steps if the above IF condition was false.
|-
|ENDIF
|Ends the above IF statement
|-
|TEXTVIEWER:filename:varname
|Opens a text viewer using the specified filename (located within data/dipscripts/text). Second parameter is optional - if specified, indicates a LONG script variable which will be set based on the hyperlink selected.
|-
|CONSTRUCTTOPICLIST
|Builds a list of appropriate discussion topics (discuss current agreement, request peace treaty, propose tree quota, establish export agreement, establish import agreement, make liaison request, or make small talk), based on the type of civilization the diplomat came from.
|-
|TOPICDISCUSSION
|Discuss all topics selected via CONSTRUCTTOPICLIST.
|-
|DISCUSS:length
|Inserts a delay into the meeting. Valid lengths are SHORT and LONG.
|-
|HISTORY_DIPEV:type
|Records a historical event once the diplomat leaves your fortress. The only valid event type is FIRSTCONTACT, used by the Elves to control whether or not they will send their diplomat to propose logging quotas.
|-
|ACTION:type:subtype
|Performs a simple action. Only valid action is DREAM:UNDEAD_ARMY, which causes one of your dwarves to have a nightmare about an army of the undead.
|-
|DIPEVENT:parm1:parm2:parm3:parm4:parm5
|Has no effect. Most likely, pre-release versions used this to perform special actions.
|-
|INVASION:parm
|Has no effect. Most likely, pre-release versions used this to trigger invasions of specific types.
|}

==Variables==
Dipscripts (and their text screens) can make use of any number of special variables. Each variable has a class, name, and type.

===Readable variables===
{|
! Class
! Name
! Type
! Description
|-
|GLOBAL
|UNIT_WIZARD
|Undefined
|Not implemented - presumably, this used to be used for a [[wizard]] visiting your fortress (and threatening an undead invasion).
|-
|GLOBAL
|HEALTHY_DWARF
|Unit
|A random healthy dwarf, selected from your population.
|-
|GLOBAL
|DIPLOMACYFLAG_SUCCESS
|Integer
|Value 4, to be used with DIPEV:ADD_FLAG and DIPEV:REMOVE_FLAG.
|-
|GLOBAL
|DIPLOMACYFLAG_FAILURE
|Integer
|Value 2, to be used with DIPEV:ADD_FLAG and DIPEV:REMOVE_FLAG.
|-
|GLOBAL
|YOURCIV
|Entity
|Your fortress's parent civilization.
|-
|GLOBAL
|YOURFORT
|Plot Info
|Your fortress itself.
|-
|GLOBAL
|TREESREMOVED
|Integer
|The number of [[tree]]s that have been destroyed at your fortress, whether by cutting them down or by smashing them with [[ballista]] bolts.
|-
|GLOBAL
|NULL
|Null
|A null pointer. Used during comparisons to detect unset variables.
|-
|GLOBAL
|LOCAL_DEMON
|Historical Figure
|The [[demon]] imprisoned beyond the [[raw adamantine]] in your embark region.
|-
|GLOBAL
|LOCAL_LARGE_PREDATOR
|Creature Definition
|A random large predator that can be found near your fortress.
|-
|GLOBAL
|RANGE.min.max
|Integer
|A random number between 'min' and 'max'.
|-
|GLOBAL
|number
|Integer
|An explicit integer value.
|-
|DIPEV
|DIPLOMAT
|Unit
|The diplomat who is meeting with your noble.
|-
|DIPEV
|ASSOCIATE
|Unit
|The diplomat's associate. By default, this is null.
|-
|MEETING
|ACTOR
|Unit
|The diplomat who is meeting with your noble.
|-
|MEETING
|NOBLE
|Unit
|Your noble who is meeting with the diplomat.
|-
|DIPSCRIPT
|varname
|Integer or Unit
|A variable you have declared using the VAR command above.
|}

===Writable variables===
{|
! Class
! Name
! Type
! Description
|-
|GLOBAL
|TREESREMOVED
|Integer
|The number of [[tree]]s that have been destroyed at your fortress.
|-
|DIPEV
|ADD_FLAG
|Integer
|A specific flag to set in the diplomacy event. Valid values are GLOBAL:DIPLOMACYFLAG_SUCCESS (4) and GLOBAL:DIPLOMACYFLAG_FAILURE (2).
|-
|DIPEV
|REMOVE_FLAG
|Integer
|A specific flag to set in the diplomacy event. Valid values are GLOBAL:DIPLOMACYFLAG_SUCCESS (4) and GLOBAL:DIPLOMACYFLAG_FAILURE (2).
|-
|DIPEV
|DIPLOMAT
|Unit
|The diplomat who is meeting with your noble. Changing this may have unexpected effects.
|-
|DIPEV
|ASSOCIATE
|Unit
|The diplomat's associate. If you set this to a unit in your fortress, then that unit will bid you farewell and depart from your fortress with the diplomat.
|-
|MEETING
|ACTOR
|Unit
|The diplomat who is meeting with your noble. Changing this may have unexpected effects.
|-
|MEETING
|NOBLE
|Unit
|Your noble who is meeting with the diplomat. Changing this may have unexpected effects.
|-
|DIPSCRIPT
|varname
|Integer or Unit
|A variable you have declared using the VAR command above.
|}

===Displayable variables===
Some of the above variables can be displayed in custom screens opened by the TEXTVIEWER command using the syntax [C:VAR:class:name] (to set the text color) and [VAR:format:class:name] to output the value in a particular format. Certain formats are only valid with specific types - trying to use it on the wrong type will likely result in a blank string.
{|
! Format
! Type
! Description
|-
|TITLENAME
|Unit
|Displays the unit's profession. Noble professions will be prefixed with "the ".
|-
|HISTNAME
|Historical Figure
|Displays the historical figure's name and race.
|-
|NAME_PLURAL
|Creature Definition
|Displays the plural name for the creature selected.
|-
|NATIVENAME
|Unit
|Displays the unit's name in its native language.
|-
|NATIVENAME
|Entity
|Displays the civilization's name in its native language.
|-
|NATIVENAME
|Plot Info
|Displays your fortress's name in its native language.
|-
|TRANSLATEDNAME
|Unit
|Displays the unit's name, translated into English.
|-
|TRANSLATEDNAME
|Entity
|Displays the civilization's name, translated into English.
|-
|TRANSLATEDNAME
|Plot Info
|Displays your fortress's name, translated into English.
|-
|[anything]
|Integer
|Displays the number in decimal form.
|}

@@ Line 3: / Line 3: @@
 A '''dipscript''', or "diplomat script", is what controls the behavior of visiting [[diplomat]]s when they meet with your [[noble]]s. Dipscripts were originally used to trigger special events at specific points in the lifetime of one's fortress (such as undead invasions), but much of this was stripped out by the time the first version of Dwarf Fortress was actually released.
-Only 5 different dipscripts are ever executed during gameplay, and they are defined in records 13-17 of the game's "index" file: ELVES_FIRSTCONTACT, HUMAN_STANDARD, DWARF_LIAISON, HUMAN_TRADE, and ELVES_STANDARD. The dipscript files themselves are compressed and scrambled, making them difficult to edit (in later versions, they are only compressed).
+Only 5 different dipscripts are ever executed during gameplay, and they are defined in records 13-17 of the game's "index" file: ELVES_FIRSTCONTACT, HUMAN_STANDARD, DWARF_LIAISON, HUMAN_TRADE, and ELVES_STANDARD. The dipscript files themselves are compressed and scrambled, requiring [[User:Quietust/wtf23a.php|special tools]] in order to edit them (in later versions, they are only compressed).
 ==Script Tokens==

@@ Line 50: / Line 50: @@
 |Performs a simple action. Only valid action is DREAM:UNDEAD_ARMY, which causes one of your dwarves to have "[[Thought|a terrifying nightmare about an army of the dead]]".
 |-
-|DIPEVENT:parm1:parm2:parm3:parm4:parm5
+|DIPEVENT:unit_class:unit_name:dipscript:outcome_class:outcome_name
 |Has no effect. Most likely, pre-release versions used this to perform special actions.
 |-
-|INVASION:parm
+|INVASION:type
 |Has no effect. Most likely, pre-release versions used this to trigger invasions of specific types.
 |}

@@ Line 71: / Line 71: @@
 |UNIT_WIZARD
 |Undefined
-|Not implemented - presumably, this used to be used for a [[wizard]] visiting your fortress (and threatening an undead invasion).
+|Not implemented - presumably, this used to be used for a [[wizard]] visiting your fortress to bring a random healthy dwarf (see below) on a quest to thwart another evil wizard.
 |-
 |GLOBAL

@@ Line 12: / Line 12: @@
 |-
 |INITIAL_LOAD
-|Purpose unclear - all dipscripts have this as their second line
+|Presumably indicates that the dipscript should be loaded on game startup instead of on-demand. All of the default dipscripts specify this, as the game does not appear to contain logic for dynamic loading.
 |-
 |DIPSCRIPT:name

@@ Line 33: / Line 33: @@
 |-
 |TEXTVIEWER:filename:varname
-|Opens a text viewer using the specified filename (located within data/dipscripts/text). Second parameter is optional - if specified, indicates a LONG script variable which will be set based on the hyperlink selected.
+|Opens a [[text viewer]] using the specified filename (located within data/dipscripts/text). Second parameter is optional - if specified, indicates a LONG script variable which will be set based on the choice selected.
 |-
 |CONSTRUCTTOPICLIST

@@ Line 42: / Line 42: @@
 |-
 |DISCUSS:length
-|Inserts a delay into the meeting. Valid lengths are SHORT and LONG.
+|Inserts a delay into the meeting. Valid lengths are SHORT (500-1000 [[FPS|steps]], about a half a day) and LONG (2-4 days).
 |-
 |HISTORY_DIPEV:type

@@ Line 48: / Line 48: @@
 |-
 |ACTION:type:subtype
-|Performs a simple action. Only valid action is DREAM:UNDEAD_ARMY, which causes one of your dwarves to have a nightmare about an army of the undead.
+|Performs a simple action. Only valid action is DREAM:UNDEAD_ARMY, which causes one of your dwarves to have "[[Thought|a terrifying nightmare about an army of the dead]]".
 |-
 |DIPEVENT:parm1:parm2:parm3:parm4:parm5

@@ Line 5: / Line 5: @@
 Only 5 different dipscripts are ever executed during gameplay, and they are defined in records 13-17 of the game's "index" file: ELVES_FIRSTCONTACT, HUMAN_STANDARD, DWARF_LIAISON, HUMAN_TRADE, and ELVES_STANDARD. The dipscript files themselves are compressed and scrambled, making them difficult to edit (in later versions, they are only compressed).
-The following tokens can be specified in a dipscript:
+==Script Tokens==
-{|
+{| {{prettytable}}
 ! Token
 ! Meaning
@@ Line 60: / Line 61: @@
 ===Readable variables===
-{|
+{| {{prettytable}}
 ! Class
 ! Name
@@ Line 153: / Line 155: @@
 ===Writable variables===
-{|
+{| {{prettytable}}
 ! Class
 ! Name
@@ Line 202: / Line 205: @@
 ===Displayable variables===
 Some of the above variables can be displayed in custom screens opened by the TEXTVIEWER command using the syntax [C:VAR:class:name] (to set the text color) and [VAR:format:class:name] to output the value in a particular format. Certain formats are only valid with specific types - trying to use it on the wrong type will likely result in a blank string.
 {|
 ! Format
 ! Type