This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
script:reference [2018-12-15 22:12] skyjake |
script:reference [2019-11-18 12:59] skyjake |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Doomsday Script reference ====== | + | ====== Doomsday Script reference guide ====== |
- | + | ||
- | + | ||
- | This article describes the Doomsday Script language and its role in the [[:Doomsday 2]] architecture. | + | |
+ | This article describes the Doomsday Script language and its role in [[:Doomsday 2]]. | ||
===== Overview ===== | ===== Overview ===== | ||
+ | Doomsday Script in 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. | ||
- | As a scripting language, Doomsday Script serves in many roles, for instance managing engine configuration and controlling [[assets:model#timelines|3D model asset animation]]. | + | Below is an example of the syntax: |
- | + | ||
- | 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. | + | |
- | + | ||
- | Example: | + | |
def exampleFunc(a) | def exampleFunc(a) | ||
Line 24: | Line 19: | ||
- | 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''. | * The amount of indentation whitespace has no 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 no non-modifiable tuples, just arrays:<code>array = [1, 2, 3, 4] | ||
Line 35: | Line 30: | ||
* 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 ===== | + | ===== Examples ===== |
- | ==== Built-in types ==== | + | * [[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]] | ||
- | * Number | + | ===== Using Doomsday Script ===== |
- | * Text | + | |
- | * Time | + | |
- | * Array | + | |
- | * Dictionary | + | |
- | * Function | + | |
- | * Record | + | |
+ | As of [[version:2.2]], scripts can be used for the following: | ||
- | ==== Built-in constants ==== | + | * **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 | ||
+ | * **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., 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#scripting|onLoad/onUnload callbacks]] | ||
+ | * **Things:** | ||
+ | * [[.module:World#World.Thing|Query hit points]] | ||
+ | * [[.module:World#World.Thing|Start a sound]] | ||
+ | * [[ded:thing#on_touch|"On touch" script]] | ||
- | * True | + | ===== Language reference ===== |
- | * False | + | |
- | * None | + | |
- | * Pi | + | |
+ | See the [[language|Language reference]] for information about the syntax, and built-in functions and modules. | ||
- | ==== Built-in functions ==== | ||
- | |||
- | |||
- | ^ Function ^ Description | | ||
- | | [[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 ===== | ||
- | |||
- | [[script:walkthrough:start|Doomsday Script feature walkthrough]] | ||
- | |||
- | |||
- | ===== 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. | ||
- | |||
- | |||
- | ===== See also ===== | ||
- | |||
- | * [[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]] |