Utility:DFusion

DFusion info page

Thread for discussions: Thread

Usage

Dfusion plugin offers two DFhack commands: 'dfusion' and 'lua'.

lua

Runs an interactive lua console. For more on lua commands see Lua reference manual or google "lua". Also this command could be ran with filepath as an argument. Then it runs that file as a lua script file. E.g. lua dfusion/temp.lua runs a file <your df path>/dfusion/temp.lua.

dfusion

First this command runs all plugins' init.lua part then show a menu. Type number to run specified plugin.

How to

This section explains in detail some of more complex things that could be done with dfusion.

OnFunction

There are two parts to OnFunction: adding new triggers and using already existing triggers. To add new trigger you must know exact location of function call (and what it does) also it would help a lot if you know what registers correspond to what data. Usually this could be worked out by analysing call stack after setting a data breakpoint (watch in GDB) and then guessing what does what. Using already existing triggers is way simpler. Adding a callback (a function to be called when a trigger is encountered) is done by onfunction.SetCallback(name,function). For possible names see locations.lua (at the time of writing there is "Move" and "Die" both in Linux and Windows). Possible use of it:

function DeathMsg(values)
	local name
	name=engine.peek(values[onfunction.hints["Die"].creature],ptt_dfstring)
	print(name:getval().." died")
end
onfunction.SetCallback("Die",DeathMsg)

In this example we bind 'DeathMsg' function to "Die" trigger. Values argument has all the registers and a return address. So we lookup from witch register do we need to read the creature pointer ( values[onfunction.hints["Die"].creature ) and read a string just from the beginning (usually the creature starts with his name). Then print it to the console.

Note: there can be only one callback per trigger. Also if you know any more trigger locations please share :)