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 [2019-11-17 09:15]
skyjake
script:reference [2020-04-04 08:04] (current)
skyjake [Using Doomsday Script]
Line 1: Line 1:
 ====== Doomsday Script reference guide ====== ====== Doomsday Script reference guide ======
  
- +This article describes the Doomsday Script language and its role in [[:Doomsday 2]].
-This article describes the Doomsday Script language and its role in the [[:Doomsday 2]] architecture. +
  
 ===== Overview ===== ===== 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.
  
-As a scripting language, Doomsday Script serves in many roles, for instance ​managing engine configuration and controlling [[assets:​model#​timelines|3D model asset animation]].+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.
  
-Doomsday Script ​is not a compiled language and thus is not intended for high-performance or time-critical tasks. Game plugins written in native code should be used for processing-intensive functionality. +Below is an example of the syntax:
- +
-Example:+
  
   def exampleFunc(a)   def exampleFunc(a)
Line 24: Line 21:
  
  
-The syntax ​of the language ​is heavily influenced by Ruby and Python, with a few notable differences:​+The syntax is heavily influenced by Python ​and Ruby, with a few notable differences:​
  
-  * The amount of indentation ​whitespace has no meaning. Compounds are explicitly closed with ''​end''​.+  * 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>​   * A colon ('':''​) always indicates a single-line compound that does not need to be closed: <​code>​def func2(): return '​World'</​code>​
-  * Objects are classless and called [[Record]]s. They correspond ​native ''​de::​Record''​ instances:<​code>​record myrec+  * 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>​ myrec.newMember = 100</​code>​
-  * There are no non-modifiable tuples, just arrays:<​code>​array = [1, 2, 3, 4]+  * There are only modifiable arrays. Non-modifiable tuples ​are not supported:<​code>​array = [1, 2, 3, 4]
 array[1] = 100 array[1] = 100
 # array is now [1, 100, 3, 4]</​code>​ # 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.   * 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.
  
-===== Built-ins ​=====+===== Tutorial ​=====
  
-==== Built-in types ====+==== Feature walkthrough ​====
  
-  *  Number +The following pages walk though the features of Doomsday Script with brief code snippets: 
-  ​* ​ Text +<doctoc start=script:​walkthrough:​basic_expressions,​useheading=1>​
-  *  Time +
-  *  Array +
-  *  Dictionary +
-  *  Function +
-  *  Record+
  
 +==== Examples ====
  
-==== Built-in constants ====+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.)
  
-  *  True +  * [[https://​github.com/​skyjake/​Doomsday-Engine/​blob/​master/​doomsday/​apps/​client/​net.dengine.client.pack/​modules/​controllers.ds|Game controller presets script]] 
-  *  ​False +  * [[https://​github.com/​skyjake/​Doomsday-Engine/​blob/​master/​doomsday/​tests/​test_script/​kitchen_sink.ds|The "​Kitchen Sink" test script]]
-  *  None +
-  *  Pi+
  
 +===== Using Doomsday Script =====
  
-==== Built-in functions ====+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]]
  
-^ Function ^ Description | +In older versions: ​[[/script/​reference?​rev=1576480962#​using_doomsday_script|2.2]]
-[[deserialize_function_]]| reconstruct data from an array of bytes | +
-| [[dictkeys_function_]]| returns the keys of a dictionary as an array | +
-| [[dictvalues_function_]]| returns the values of a dictionary as an array | +
-| [[dir_function_]]| returns the variable names of a namespace as an array | +
-| [[eval_function_]]| parses and executes argument as a script, returns result ​| +
-| [[file_function_]]| returns a [[core.file]] object | +
-| [[floor_function_]]| rounds a number down to an integer | +
-| [[globals_function_]]| returns the global namespace as a record | +
-| [[len_function_]]| determines the length/size of the argument | +
-| [[locals_function_]]| returns the local namespace as a record | +
-| [[members_function_]]| returns the members of a record as a dictionary | +
-| [[number_function_]]| converts argument to a number value | +
-| [[record_function_]]| duplicates a record or creates an empty one | +
-| [[serialize_function_]]| serializes data into an array of bytes | +
-| [[subrecords_function_]]| returns the subrecords of a record as a dictionary | +
-| [[text_function_]]| converts argument to a text string | +
-| [[time_function_]]| converts argument to a time | +
-| [[timedelta_function_]]| calculates difference between two times (as seconds) | +
-| [[typeof_function_]]| returns type of value as a text string |+
  
  
-===== Feature walkthrough =====+==== Editor support ​====
  
-[[script:walkthrough:start|Doomsday Script feature walkthrough]]+  * 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]].
  
-===== Standard library modules ===== 
- 
- 
-The Doomsday Script Standard Library consists of a collection of native built-in modules and script modules. 
- 
-  *  [[.module:​App]]:​ application core (native) 
-  *  [[.module:​appconfig]]:​ application configuration variables (imported by [[.module:​Config]]) 
-  *  [[.module:​Config]]:​ configuration variables (special persistent namespace) 
-  *  [[.module:​Core]]:​ built-in classes and core language functionality 
-  *  [[.module:​Defs]]:​ definitions read from [[DED]] files 
-  *  [[.module:​DisplayMode]]:​ information about display modes (native) 
-  *  [[.module:​gui]]:​ routines related to the graphical user interface 
-  *  [[.module:​Input]]:​ input subsystem (native) 
-  *  [[.module:​math]]:​ math routines (native) 
-  *  [[.module:​recutil]]:​ routines for manipulating records 
-  *  [[.module:​SavedSession]]:​ routines for manipulating savegames (native) 
-  *  [[.module:​Version]]:​ version information (native) 
- 
- 
-===== Feature status ===== 
- 
-Doomsday Script is not yet fully utilized (as of [[version:​2.1]]). Upcoming uses include: 
-  * Backend of the console prompt, console variables and commands. 
-  * Manipulating level data and game objects. 
- 
- 
-===== Examples ===== 
- 
-  *  [[https://​github.com/​skyjake/​Doomsday-Engine/​blob/​master/​doomsday/​tests/​test_script/​kitchen_sink.ds|The "​Kitchen Sink" test script]] 
-  * [[https://​github.com/​skyjake/​Doomsday-Engine/​blob/​master/​doomsday/​apps/​client/​net.dengine.client.pack/​modules/​controllers.ds|Game controller presets script]] 
script/reference.1573974958.txt.gz · Last modified: 2019-11-17 09:15 by skyjake