DinkLua
0.85 and later contain a port of Phoenix's DinkLua scripting backend. DinkLua is infinitely more powerful than DinkC and contains mind-blowing features such as loops and string variables!
A brief introduction is available from the author here, and a more general Lua tutorial to get you started may be found here, or a short reference here.
Using Lua means that one not only has access to inbuilt libraries for things such as mathematics and string manipulation, but also the entire Lua ecosystem.
Enabling DinkLua
The Lua backend is not switched on by default and must be manually enabled in dink.ini. Adding the line dinklua_enable anywhere in dink.ini will switch it on at launch. If one would like to use Lua exclusively, the line dinkc_off may also be specified.
Script execution precedence starts from Lua files in your mod data, followed by those in Dink's data, before looking for DinkC d and c files, assuming DinkC is on as well.
Writing Lua scripts
As Lua is a standardised programming language, there are numerous IDEs and text editor plugins that may assist you. One such IDE is ZeroBrane Studio designed specifically for Lua.
In Visual Studio Code, having the init.lua environment file open in another tab will provide some degree of autocomplete.
Programming conventions
As a general reminder, most existing DinkC commands are available in the "dink" table. For example DinkC's playmidi() becomes dink.playmidi().
Another potential gotcha is in values that in DinkC are either 1 or 0. These are bools specified as "true" or "false" in Lua.
Extra SFX features
New features have been added to SFX playback in 0.86. A sound can be played back with its reference stored like so:
With "repeat" being true or false, and hz optionally zero for native speed. The parameters apart from sound number are now optional, and you can write the above as:
This will cause the sound to be played back at its native speed, unattached to a sprite, and no looping in case you just want a "one-shot" sound effect somewhere.
Sound properties can be accessed and set like so:
Unlike in DinkC, the default volume of a sound is 100 rather than 10,000. Along with this, in 0.86 and later one may also get and set:
pan - from -100 to 100 with zero being centre
speed - from 1 to whatever with 100 being default
hz - control the sampling playback rate independently of speed.
pause - accepts a bool value true/false
repeating - accepts a bool, allows you to set sounds looping after the fact
looppoint - accepts a value in seconds for repeating sounds to offset playback
loopcount - get the amount of times a repeating sound has looped (get only)
pos - get the current playback position in seconds (get only)
There are also several new functions for sounds:
Along with fade_vol, there is also:
fade_pan(pan, time)
fade_speed(speed, time)
schedule_pause(time)
schedule_stop(time)
With time specified in seconds
As well as a few oscillators:
oscillate_vol(min, max, time)
oscillate_pan(min, max, time)
oscillate_speed(min, max, time)
These oscillators may be reset/cancelled by setting the relevant oscillating parameter to something else. e.g. set pan to zero.
dink.actually_kill_all_sounds()will halt all playing sound effects
Extra music commands
Starting with 0.90 is the ability to adjust BGM as it's playing:
dink.set_music_tempo(float tempo)will adjust the tempo of the playing track. 1.0 is the default, with 0.5 being half.dink.is_music_playing()returns true or false.
New in 0.92
dink.todisk(table, filename)will save a table or other variable to filename located in dmoddirdink.fromdisk(filename)returns a table or other variable from filename in dmoddir.dink.copy_to_clipboard(string)copies string to the clipboard.dink.get_cheat()returns a bool indicating the use of the cheat window.dink.playmidi(file, fadein)accepts an optional ms value for fading in the playback of filedink.fade_out_music(time)will fade out the currently-playing BGM over the specified amount of time in ms.player.get_speedwill return the internal dinkspeed variable.