Doomsday Script reference guide

This article describes the Doomsday Script language and its role in Doomsday 2.

Doomsday Script is a scripting language with features such as a class-based object system, and exceptions. It is designed to harmoniously work together with Doomsday's native code and objects.

Scripting is used for several things internally, for example managing engine configuration and controlling 3D model asset animation. Doomsday Script is not a compiled language and thus is not intended for high-performance or time-critical tasks. Game plugins, for instance, should be written in native code.

Below is an example of the syntax:

def exampleFunc(a)
    if a
        return "It is true!"
    else
        return "Nay, it is false."
    end
end
print exampleFunc(True)

The syntax is heavily influenced by Python and Ruby, with a few notable differences:

• Unlike Python, the amount of indentation whitespace has no special meaning.
• Compounds are explicitly closed with end.
• A colon (:) always indicates a single-line compound that does not need to be closed:

  def func2(): return 'World'

• Objects are weakly typed: they may have one or more superclass objects that provide common members, but otherwise there is no type safety or checking. Objects are called Records and they represent native de::Record instances:

  record myrec
  myrec.newMember = 100

• There are only modifiable arrays. Non-modifiable tuples are not supported:

  array = [1, 2, 3, 4]
  array[1] = 100
  # array is now [1, 100, 3, 4]

• There are a couple of special assignment operators. Global assignment (:=) will assign into variables in parent scopes if no local variable with the given name is found. Weak assignment (?=) will only assign a value if a variable has not yet been created.

The following pages walk though the features of Doomsday Script with brief code snippets:

• Basic expressions
• Operator expressions
• Statements and compounds
• Exceptions
• Records
• Functions
• Scopes
• Miscellaneous

These larger examples may be examined to get a better feel of what Doomsday Script is like in practice. (Spoiler alert: Very much like Python.)

• Game controller presets script
• The "Kitchen Sink" test script

As of 2.3, scripts can be used for the following:

• Animating 3D models:
  • Initializing the animator of a thing (onInit)
  • When receiving damage or when the thing state changes
  • At specific points in time
  • Manipulate shader variables, render passes, and the active material
• Application:
  • Loading fonts
  • Callbacks for game load/unload
• Audio:
  • Start local sounds
• Configuration:
  • Applications run a Config.ds script at startup
  • Client runs bootstrap.ds when initialization is complete (e.g., maintenance during upgrades, SF2 soundfont caching)
• Console:
  • List, get, and set cvars
  • Interactive scripting prompt (toggle in taskbar)
• Definitions:
  • Accessing currently loaded DEDs via the Defs module
• Files:
  • Reading/writing files and folders using File objects
• Game:
  • Show a HUD message
• Input:
  • Binding controls and events (e.g., Input.bindEvent)
  • Game controller presets
• Packages:
  • Modify package metadata and assets (__init.ds__)
  • Adding modules to the import path
  • onLoad/onUnload callbacks
• Players:
  • Query health, armor, and powerups
  • Earthquake effect
• Things:
  • State action function
  • Attack, drop items, start sounds
  • Query and change thing flags
  • Query hit points, type, height, position, and momentum
  • Change momentum
  • "On touch" and "On death" scripts

In older versions: 2.2

• Visual Studio Code: skyjake.doomsdaylang package
• Syntax definitions in TextMate format for compatible editors

See the Language reference for information about the syntax, and built-in functions and modules.