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 revisionPrevious revision
Next revision
Previous revision
script:reference [2019-11-19 10:56] – [Feature walkthrough] skyjakescript:reference [2020-11-12 15:29] (current) skyjake
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, 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]].