User Tools

Site Tools


script:reference

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
script:reference [2018-12-16 09:22]
skyjake [See also]
script:reference [2020-04-04 08:04] (current)
skyjake [Using Doomsday Script]
Line 1: Line 1:
 +====== 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, whitespace used for indentation 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]].