DinkLua

Versions from 0.85 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:

sfx = dink.playsound(soundnum, hz, rand, sprite, repeat)

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:

sfx = dink.playsound(num)

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:

sfxvol = sfx.vol
player:say("The volume of this sound is set at " .. sfxvol)
-- make it 1/10th as loud
sfx.vol = sfx.vol / 10

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:

-- fade the sfx to half normal volume over a period of 5 seconds
sfx:fade_vol(50, 5)

Along with fade_vol, there is also:

fade_pan(pan, time)
fade_speed(speed, time)
schedule_pause(time)
schedule_stop(time)

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.

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.

Last modified: 16 April 2024