====== Doomsday Script reference guide ======

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

===== Overview =====

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 [[assets:model#timelines|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: <code>def func2(): return 'World'</code>
  * 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 [[Record]]s and they represent native ''de::Record'' instances:<code>record myrec
myrec.newMember = 100</code>
  * There are only modifiable arrays. Non-modifiable tuples are not supported:<code>array = [1, 2, 3, 4]
array[1] = 100
# array is now [1, 100, 3, 4]</code>
  * 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.

===== Tutorial =====

==== Feature walkthrough ====

The following pages walk though the features of Doomsday Script with brief code snippets:
<doctoc start=script:walkthrough:basic_expressions,useheading=1>

==== Examples ====

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

  * [[https://github.com/skyjake/Doomsday-Engine/blob/master/doomsday/apps/client/net.dengine.client.pack/modules/controllers.ds|Game controller presets script]]
  * [[https://github.com/skyjake/Doomsday-Engine/blob/master/doomsday/tests/test_script/kitchen_sink.ds|The "Kitchen Sink" test script]]

===== Using Doomsday Script =====

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

  * **Animating 3D models:**
    * [[assets:scripting_with_stateanimator|Initializing the animator of a thing (onInit)]]
    * [[assets:scripting_with_stateanimator|When receiving damage or when the thing state changes]]
    * [[assets:model#timelines|At specific points in time]]
    * Manipulate shader variables, render passes, and the active material
  * **Application:**
    * Loading fonts
    * Callbacks for game load/unload
  * **Audio:**
    * [[.module:audio|Start local sounds]]
  * **Configuration:**
    * [[https://git.skyjake.fi/doomsday/engine/src/branch/master/doomsday/sdk/libcore/net.dengine.stdlib.pack/modules/Config.ds|Applications run a Config.ds script at startup]]
    * [[https://git.skyjake.fi/doomsday/engine/src/branch/master/doomsday/apps/client/net.dengine.client.pack/modules/bootstrap.ds|Client runs bootstrap.ds when initialization is complete (e.g., maintenance during upgrades, SF2 soundfont caching)]]
  * **Console:**
    * [[.module:console|List, get, and set cvars]]
    * [[guide:task_bar_and_console#console|Interactive scripting prompt (toggle in taskbar)]]
  * **Definitions:**
    * [[script:module:defs#lookups|Accessing currently loaded DEDs via the Defs module]]
  * **Files:**
    * Reading/writing files and folders using File objects
  * **Game:**
    * [[.module:Game|Show a HUD message]]
  * **Input:**
    * Binding controls and events (e.g., [[.module:input|Input.bindEvent]])
    * [[https://git.skyjake.fi/doomsday/engine/src/branch/master/doomsday/apps/client/net.dengine.client.pack/modules/controllers.ds|Game controller presets]]
  * **Packages:**
    * [[fs:packages#metadata|Modify package metadata and assets (__init.ds__)]]
    * [[fs:packages#scripting|Adding modules to the import path]]
    * [[fs:packages#script
    * ing|onLoad/onUnload callbacks]]
  * **Players:**
    * [[.module:App#App.Player|Query health, armor, and powerups]]
    * [[.module:App#App.Player|Earthquake effect]]
  * **Things:**
    * [[ded:state#action|State action function]]
    * [[.module:World#attack|Attack, drop items, start sounds]]
    * [[.module:World#flags|Query and change thing flags]]
    * [[.module:World#health|Query hit points, type, height, position, and momentum]]
    * [[.module:World#worldthing|Change momentum]]
    * [[ded:thing#on_touch|"On touch" and "On death" scripts]]

In older versions: [[/script/reference?rev=1576480962#using_doomsday_script|2.2]]


==== Editor support ====

  * Visual Studio Code: [[https://marketplace.visualstudio.com/items?itemName=skyjake.doomsdaylang|skyjake.doomsdaylang package]]
  * [[https://git.skyjake.fi/doomsday/skyjake.doomsdaylang/src/branch/master/syntaxes|Syntax definitions in TextMate format]] for compatible editors
===== Language reference =====

See the [[language|Language reference]] for information about the syntax, and  built-in functions and [[script:language#modules|modules]].