The Dink Network

The duckingly prolific RobJ (with website support from the shadowy figure known as Kyle) has revised and republished the DinkC Reference Guide. It is no longer a lengthy txt document or unviewable 'CHM' file. Instead, it is a clean and efficient web site, and thoughtfully maintained via a GitHub repository. There's also a permanent link in the 'Partners' section to your right.

Whereas the earlier versions of the DinkC Reference had significant errors and hadn't been updated in about 15 years, this version boasts a few major changes such as:

• Anything in the Reference (functions or general guides) that behaves differently between version of Dink and FreeDink is clearly shown, with version text tags and also color coded.
• Changes to many of the guides to make them more understandable, with extra stuff added to explain some common errors, and fixed some stuff that was incorrect.
• Fixed a lot of incorrect information given in the "Graphics" section, particularly surrounding things that can or cannot be used in the "init" function, but also some other stuff too.
• Where warnings are given for errors or flawed commands, a workaround example is provided, if one is possible.
• Many functions corrected, some re-written.

For a glimpse of the minor changes, please see the comments.

• editor_seq & editor_frame: to show that -1 works to get value.
• init: updated version difference given, to explain that the 'dir.ff' packing requirement for graphics to work well is only needed for Dink < 1.08 and not for 1.08 or FreeDink.
• preload_seq: A warning about a potential error causing sprites to be created with incorrect hardbox, and that using preload_seq for the fix, means this command is still useful in modern versions.
• debug: A warning about freedink 109.6 bloating a debug.txt files very quickly with hundreds of "surface does not have colorkey" reports.
• disable_all_sprites: Added info that the functions does not work as intended, and provided a workaround example in DinkC to accomplish exactly the same outcome.
• enable_all_sprites: Same as disable_all_sprites, but in reverse.
• external: A warning that calling a procedure with external will cause the calling script to continue past } and into code afterwards.
• fade_down: Added info about text becoming barely readable on fade down in FreeDink, and a work-around given.
• get_version: A note that FreeDink engine versions will return 108, and a link to Verion Checker file on TDN for if FreeDink version differentiation is required.
• hurt: Added a bit of information here for varying behavior of this function between <1.08, and 1.08/freedink.
• initfont: Info on diffrent behavior between versions and how to get this function to work most of the time
• kill_cur_item: Warning of error where script stops executing when this function is called causing a status bar bug, with work-around fix given.
• kill_cur_magic: Similar to kill_cur_item changes
• kill_this_magic: Warning of bugs when calling this function, with work-around fix given
• load_palette: Warning of flawed function and advised to use copy_bmp_to_screen for palette changes instead
• make_global_function: Warning of flawed function
• map_hard_tile: Corrected index range.
• map_tile: Corrected index range, added tip of using larger 600x550 tilesets, gave updated DinkC example based on new range and added a link to google sheet tile_index calculator.
• playsound: Added warning of FreeDink 109.6 returning the soundbank number +1
• say_xy & say_stop_xy: Made corrections in that the text will actually be displayed at int x plus 320.
• script_attach: Correction made in that this function updates active_sprite attached to the script, but not vise versa, and links to a DN thread for those seeking better understanding.
• sound_set_kill, sound_set_survive, sound_set_vol: Warning added of FreeDink 109.6 returning the soundbank number plus 1.
• sp_active: corrections made.
• spclip: Edits made to all sp_clip functions to fix incorrect information. Examples added on how to initialize DinkC clipping without prior clipping required from the editor.
• sp_custom: Version difference information added
• sp_exp: Note about exp given for missile kill regardless of where the missile came from (prior DinkC Ref's specifically state only player missiles will credit the exp to the player)
• sp_script: Corrections made based on version differences. Also added info that the main procedure will execute on the new script.
• sp_touch_damage: Added an example of leveraging prior mentioned engine oversight to also detect when dink stops touching a sprite.
• sp_x & sp_y: Added a tip that these functions should not be used to get the x or y of a shadow sprite, otherwise it can return an incorrect value.

holy shit, you even got rid of the dind translaty thing and dinkfan

now, time to have a new edition of this thing printed for all to collect

Nice Work!

If anyone finds any bugs or errors with the website itself, message Kyle.

For any edits to the actual documentation, you can make a pull request on the github, or if you prefer just message one of us and we can add it for you.

So far since posting, several typos have been corrected, and also I have added some more information to the hurt() function, which shows how it behaves when called at the same time as damage caused by other attacks (the Dink engine treats it all as one attack, and shows one damage text sprite with all damage factored in). There is an example there of how to leverage this to add a "critical hit" chance to any attack as well.

That's amazing. Three cheers for Robj & Kyle!

This deserves to be pinned, eh?

Probably not worth pinning since the forums activity is so low lately, and there's a permanent link over on the side bar there now.

Awesome work RobJ and Kyle!

Hello folks,

I just finished reading the updated Dink C reference and it really is an amazing piece of work. I've spent the last week re-teaching myself how to script and have made solid progress with a little romp D-mod. I wish I had found and read the Dink C Reference page earlier but I got a bit lost with all the different versions of things.

Just thought I'd say hi and thanks after a bit of invisible lurking. Happy to give some details about the project on an appropriate thread if the community would like me to.

Cheers,
James

are you gonna continue the city

I'm still deciding on whether to continue the 'City' but I'm pretty sure I have all the old files and after reading my old updates I realised I got further with it than I remember.

I wrote some plot and map ideas down and realised I wanted to give it another go so this one I'm working on is a refresher and prequel/intro to The City. If it's not too painful to actually finish a D-mod then I will keep tinkering with the one I started back in 2008.

oh, believe me, its painful to finish a dmod. the language is broken as hell and sometimes just refuses to do what you actually program.

but, maybe if you start releasing stuff, others will be more inclined to get off their asses and make stuff too. it's pretty dead right now without enough developing.

Hi Folks,
Just touching base with a brief update. Haven't really checked the forum or discord for 6 months but have done a few hours on my D-mod here and there. In the middle of another flurry of activity after getting a nasty cold.
I was going to post on discord but thought it would get lost in the sea of other stuff if I'm making only occasional appearances.

Still working on a stand alone romp D-mod called Soleless. Map finished and detailed at about 84 screens, story is mostly there with the main NPCs' scripts and quests working well. The main thing left to do is tie the quests together into an ending and make it fit. Each story based thing I've done has required a lot of relearning and trial and error, I haven't done any programming before but it's making sense again. My aim has been to make something I would find fun and humorous to play (and make) while stretching the limits of what I can do with a pretty basic understanding of DinkC. It should be pretty well detailed and compact, lots to talk to and explore but probably only an hour of gameplay at most. No idea when it will be finished but it's all planned out so can't really balloon into anything too out of control.

Hope everyone is thriving as best they can in this weird old world.

Just some listed points below to show I do still semi-regularly make updates on the DinkC Reference. A reminder if you find any errors, or anything that works different between engines for certain functions that aren't already listed, let me know and I'll add it.
I'm also slowly starting to add DinkHD and YeDink specific stuff as well to the reference pages.

Some of the updates I've done since last time:
- Updated sp_script() to show version differences.

- Added FreeDink 109.6 Linux Version warning about bug where &arg4 - &arg9 sometimes passing the last known value to a previous procedure call when they aren't specified in the current procedure call

- Added restart_game() to functions

- Added DinkHD specific functions: is_base_game(), set_disable_savestates(), show_popup(), show_quick_message(), logmsg()

- Added YeDink and DinkHD specific functions get_client_version(), get_client_fork(), get_platform(), set_music_vol()

- Added common bugs and things to note on the external() function

- Updated playsound() description and added some notes.

- Added notes on how return values work for retrieving dinks speed using sp_speed()

- Edits to fade_down() for engine differences in the way it works

- Edited sp_kill_wait() to mention that it doesn't do anything to active sprite 1(Dink), and the use of it in weapon scripts in original Dink Smallwood is redundant.

- Edited free_magic() and count_magic() to show differences regarding YeDink

- Edited make_global_function() to show that it is now fully functional in YeDink

- Fixed several typos and errors throughout

Thanks, I use this almost every day I script in DinkC

Very cool!

I'll add that the count_magic/items trouble was a leftover from Freedink, meaning it will either be the same there, or slightly different, and was likely broken for years until seseler noticed.
The valid range for map_hard_tile is 0 to 799, rather than starting at 1.
It may also be worth mentioning preload_seq being inoperable in "HD" and suggesting Simonk's init trick as a potential work-around.
On the "Variables" page, the missile_target var is stated as indicating the last known target to be hit by a missile, however this only appears to be the case if the target sprite lacks a script (someone please confirm).

Also, a nitpick on the playsound blurb, the term "soundbank number" is used, when for sake of consistency, it should be "sound number", as it's referring to sound slots rather than individual sound invocation IDs.

On the "Procedures" page, the "Predefined Procedures" list is missing duckdie().

Awesome, thanks.

I'll update all that stuff in the next day or so!

A few more things...

On the "Graphics" page, authors are advised to use "load_sequence_now" in init lines for weapon scripts, when in fact load_sequence_now and load_sequence are interpreted the same when used in init lines.
The warning on the scripting entry for init() regarding replacing sequences with a different number of frames might only apply to <=1.07 as well.
Also "HD" is incapable of parsing anything other than load_sequence(_now) in init lines. This means no set_frame_frame or whatever else.

For disable/enable_all_sprites, it's fixed now, however for freedink and 1.08 etc, it would be worth mentioning that it will fail to affect the most recent sprite created.

I could've swore I used set_sprite_info in init lines in Charlie and they worked in DinkHD but I might be remembering wrong.

I'll do some testing later and update that's stuff as well.

Does Yedink support all the ini stuff in init lines btw?

I haven't tested it myself, I was just going by this, however Simonk has mentioned that it's the case.
I haven't removed any of that init() functionality.

Hmmm.. I was just able to succesfully do set_frame_frame with init in DinkHD.

This worked by copying frame 1 of the rock sequence into frame 11 (which was the first unused frame). Then when talking to the rock, I did create_sprite to actually create it, and the sprite did in fact appear:

void main(void)
{
 init("set_frame_frame 95 11 95 1");
}

void talk(void)
{
 create_sprite(200, 200, 0, 95, 11);
}

So looks like DinkHD does accept other ini commands.

@YeoldeDink I think the line above that comment you linked in the RTDink source probably handles the rest of the commands?
This one, which is the function directly below.

Not sure why that comment is there tho, bit misleading

Hmmm, I may have been mistaken with the init("set_sprite_info...") stuff, I just had weird things happening when trying to reset depth dots on existing Dink graphics is PQ to simulate large vertical movements as Dink walks to suggest walking underwater, and then reset them once back above water. I was too lazy to modify the actual graphics themselves for all 8 directions and thought... hey let's just change the depth dot to be slowly going further down (increase Y value) during the walk cycle, so just change 6 x 8 set_sprite_info lines. But it got messed up.

And then I thought that maybe the reason why Dink's sword hit frame couldn't be changed to be more spot on rather than having to use the fist hit frame was because the frame to play the hit sound couldn't be changed via init either... but I don't think I actually tested it.

=====================================

On a side note - playmidi() works with .ogg files as well as .mid, as does assigning a number named .ogg file via a screen's properties in DinkHD, and YD.

Good catch. It tripped me up, as every other engine has a separate parser just for init lines, rather than reusing the one for when the engine boots. The implications are interesting, as it should mean you can do stuff like:

init("playmidi 1.mid")

And yes, there should definitely be some sort of addendum to playmidi() about it supporting Ogg Vorbis and MP3 at the very least.

On the "Variables" page, the missile_target var is stated as indicating the last known target to be hit by a missile, however this only appears to be the case if the target sprite lacks a script (someone please confirm).

Wait wtf. Indeed if you constantly check &missile_target (I spawned a script and had Dink say it every wait 0), it's "1" when firing at things with scripts. But then how does stuff like in the fireball script work where it does a check for is_script_attached(&missile_target) to run the die procedure on trees with scripts when you hit them, and it works? When a missile hits a scripted sprite does it actually store the correct active sprite number and then immediately revert back to storing 1?

Ok yeh, that is what it does by the looks of it in testing.. if you hit a sprite with a script it does indeed store it's active sprite number in &missile_target but on the next wait() &missile_target will change to "1". Whyyyyyyy?!

Ok double post just to say that all suggested changes above have been updated/added onto the DinkC reference.

I've also changed all instances of the version specific tag notes that specify "Dink < 1.08" to just "Dink 1.07". So it's less confusing on glance.

Fresh bump to bring the following addition of a bug to authors attention. Thanks to Drone for discovering this:

See the warning at the bottom of the page

It does seem to be DinkHD specific, since Drone couldn't seem to reproduce the bug in YeDink.

On the topic of warps, there's also the consideration of brain 6 (seq loop) warp sprites as per this thread.

"Whyyyyyyy?!"

The signature cry of a DinkC coder.

When you hear this echoing through the night, you know that someone somewhere is making a new D-Mod. Rejoice! The pain is worth it.

@Sparrowhawk:
I could not agree more!

Another couple of potential changes, in this one, it's mentioned in the last paragraph "returns the raw time at which the sprite is able to attack next. It is not entirely useful.", when it's (to my knowledge) the only way to get the engine's raw millisecond tick via dinkc, allowing for accurate checking of how much time has passed.

There's also this one where the first sentence ends with "and is not known to be used in any DinkC scripts.", when it should probably say something like "included game scripts".

@YeOldeToast

Ah, right you are. I will update. Indeed I've myself used the return value of sp_attack_wait, for certain loops. You can get more accurate than using a standard wait() command for some stuff. Although isn't this method only doable if you check sp_attack_wait on sprite 1? I've only ever used this method by doing that. If you do it on a brain 9 or 10 sprite I always assumed it would perhaps return the raw wait time til next attack, as pulled from the original reference(I never tested it).
Either way, yeh sp_attack_wait(1, -1); is certainly useful in that way, I'll update it.

It should work on any sprite anywhere if you set attack_wait to zero or one in which &return will be set to the value of the game tick (or plus 1ms if you did that).

Actually yeh, I just tested it always returns the current game tick regardless of the attack_wait setting on the sprite. Interestingly, when you do sp_attack_wait(&current_sprite, -1) it causes the sprite to ignore whatever it's current attack_wait setting is and attempt to attack immediately. lol.

But yeh, I think getting the game tick with attack_wait is under-used in dmods. I don't think there's many dmods at all that make use of it. Example uses; in Charlie, I used it for barfight cooldowns, if you started a fight in any of the bars the game tick time would be retrieved at that time, and the NPC would refuse to talk to you for 5 real minutes, saving a game would store the current elapsed time of any timers in the dmod, so that on load it could start the timer again based on the new current game tick so the 5 minutes was honored on save/load.

Same concept used to remember the amount of shield-buff time remaining on save/load, rather than cancel it or get the full buff time again each time.

I'll update it in the next DinkC ref update, with an example code snippet of use. I'll wait for the new YeDink version, so I can just update it all at once.

Just made an update to the DinkC ref, quite a big one this time.

Changes:
- For highlghting differences/obscurities in the way functions work for different versions, it now just shows differences for Dink1.07, Dink1.08, and latest version of Yedink & DinkHD. No specific versions for YeDink or DinkHD, as it would get too convoluted. It would be assumed authors should be using the latest versions. Dink1.07 remains because it's still a launch option specifically in Dmod launchers and some older Dmods were designed specifically for it.
- made coloured tags easier to read.
- Added `Version` to every function page to show which engines and specific versions the function is available in. If Engine is shown but no version, that means the function is available in all versions of that Dink Engine; this is also mentioned on the functions introduction page.
- Variable Types table in Guide>Variables to show different Dink Engine limits
- Brain 6 editor warp warning in Guide>Warps
- sp_attack_wait() to state the correct return behaviour
- sp_notouch() to correctly clarify not known to be used in any DinkC base game scripts
- scripts_used() to fix missing a line break between the last two bullet points.
- sp_script() to specify that a sprite replacing it’s own script will cause the script to be entered into the “script queue” twice.
- run_script_by_number() to specify when used on the current script number it will cause the script to be entered into the “script queue” twice.
- compare_sprite_script() to correct the description so it’s accurate to what the return value is based on.
- removed some warnings in external and custom procedures about returning script continuing past ‘}’ and into code afterwards. Not incorrect, but not specific to those commands. Happens in DinkC at the end of any procedure.
- make_global_function() to show it works in DinkHD and YeDink, and has a max limit of 99 global functions
- enable_all_sprites()/disable_all_sprites() to show that it works correctly in DinkHD and YeDink
- added get_dinkspeed() and updated set_dink_speed() to mention it.
- added set_gfx_alttext_disabled()
- added set_use_latest_fixes_level()
- preload_seq() to remove the section stating that it doesn’t work in DinkHD since it works now
- playavi() to remove all the current description which only says how it doesn’t work anymore, except in really old versions of Dink and just replaced it wtih yedink workings, since that’s the only engine it does anything in.
- added play_mod_order() YeDink function.
- sp_brain() to add YeDink specific brains 9000, 9001 and 9002
- initfont() to add that YeDink will check for a TTF file in the root of the Dmod directory as well.
- added dink.ini parms under “techniques” on the main page for Yedink specific dink.ini parms.
- removed the mention of max concurrent variables and max scripts from the introduction page. Doesn’t make sense considering the limites are in the other guide documents, and I don’t want to go adding tag differences for limits to the basic introduction dot points.
- updated variables page to show higher limit of 500 concurrent global and local variables for YeDink
- added note to math operators about /= bug when using an internal function as the divisor
- updated preface for quick mention of various Dink Engines and the use of the colored tags throughout the reference
- map_tile() to show the upper limit accessible in YeDink and to specify the same upper limit exists in DinkHD but cannot be accessed with the map_tile() command.
- A lot of updates to other functions to make the descriptions more coherent.

Updated Guide>Graphics with the following:
- Show different Dink Engine sequence, frame and set_sprite_info limits
- You do not have to set a delay - you can leave this value out and the Dink Engine will still read all the other paramaters correctly, leaving out the delay.
- Negative values do not work for depth dot paramaters
- Added max amount of set_sprite_info lines per Dink Engine.
- Added information about the Dink Engine's behaviour when setting individual paramaters to 0, and when setting all paramaeters to 0.
- Added the algorithm the Dink Engine uses to assign a default sprite depth dot and hardbox when not specified in dink.ini.

As always Robj, this is great work!

Thanks for all you do for the DN.

Many thanks for this. I really need to get more familiar/comfortable with YOD and dinklua.