User Guide for v0.9 Help

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:

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)

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 dmoddir

  • dink.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 file

  • dink.fade_out_music(time) will fade out the currently-playing BGM over the specified amount of time in ms.

  • player.get_speed will return the internal dinkspeed variable.

Last modified: 26 May 2024