v50 Steam/Premium information for editors
- v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
- Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.
Editing Utility:DFusion
Jump to navigation
Jump to search
Warning: You are not logged in.
Your IP address will be recorded in this page's edit history.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
− | |||
− | |||
== DFusion info page == | == DFusion info page == | ||
Thread for discussions: [http://www.bay12forums.com/smf/index.php?topic=93317.0 Thread] | Thread for discussions: [http://www.bay12forums.com/smf/index.php?topic=93317.0 Thread] | ||
== Usage == | == Usage == | ||
− | Dfusion plugin offers | + | Dfusion plugin offers two DFhack commands: 'dfusion', 'dfuse' and 'lua', 'runlua'. |
=== lua === | === lua === | ||
Runs an interactive lua console. For more on lua commands see [http://www.lua.org/manual/5.1/manual.html 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. | Runs an interactive lua console. For more on lua commands see [http://www.lua.org/manual/5.1/manual.html 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. | ||
Line 11: | Line 9: | ||
=== dfusion === | === dfusion === | ||
First this command runs all plugins' init.lua part then show a menu. Type number to run specified plugin. | First this command runs all plugins' init.lua part then show a menu. Type number to run specified plugin. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== dfuse === | === dfuse === | ||
Similar to dfusion but not interactive. To be used with hotkeys (later will have command support). | Similar to dfusion but not interactive. To be used with hotkeys (later will have command support). | ||
− | |||
− | |||
− | |||
== Exported functions and objects == | == Exported functions and objects == | ||
− | + | Objects differ from functions by calling convention ( using '':'' instead of '.'). Also most of the functions are grouped. | |
− | + | === Df memory object === | |
− | === | + | In the new version there is a table called "df". It holds all the global objects of DF. To get list of fields available use 'printGlobals()'. |
+ | There are also helper functions 'printFields(object)' and 'addressOf(object,[field])' | ||
+ | Using new df object is very simple: | ||
<pre> | <pre> | ||
− | + | -- to get | |
− | + | print(df.window_x) | |
+ | -- to set | ||
+ | df.window_x=1 | ||
</pre> | </pre> | ||
− | + | Some objects returned are more complex: | |
<pre> | <pre> | ||
− | + | --most complex object (afaik) | |
− | + | printFields(df.world) | |
− | |||
</pre> | </pre> | ||
− | + | At first it will be confusing, but worry not, there is a tool (dfusion->editor) that lets you edit df without writing lua code. | |
− | + | ||
− | + | Some notes: | |
− | + | Sometimes returned object is a pointer, than you need to dereference it: | |
− | |||
− | |||
<pre> | <pre> | ||
− | + | -- this gets first unit, but it's a pointer, so dereference it | |
+ | df.world.units.all[0]:deref().pos.x=0 | ||
+ | -- also as you can see 'all' is a vector (or an array) so you can access it's members by numbers. This works on flags too. | ||
</pre> | </pre> | ||
− | === | + | === Dfhack/DF interface === |
+ | These functions are sown into dfhack or modifies DF directly | ||
==== Console. ==== | ==== Console. ==== | ||
{| class="wikitable" | {| class="wikitable" | ||
Line 128: | Line 119: | ||
| pokestr | | pokestr | ||
| writes a string to memory | | writes a string to memory | ||
− | | | + | | peekstr(0x15486,"Hello world") |
|} | |} | ||
Line 162: | Line 153: | ||
These commands are exported from script files. Most of them are in "common.lua" file. | These commands are exported from script files. Most of them are in "common.lua" file. | ||
=== Patterns === | === Patterns === | ||
− | DEPRECATED use df.<subitem> | + | DEPRECATED use types[<tname>] or directly df.<subitem> |
== How to == | == How to == | ||
This section explains in detail some of more complex things that could be done with dfusion. | 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: | ||
− | |||
<pre> | <pre> | ||
− | + | function DeathMsg(values) | |
− | + | local name | |
− | + | name=engine.peek(values[onfunction.hints["Die"].creature],ptt_dfstring) | |
− | function | + | print(name:getval().." died") |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
end | end | ||
− | + | onfunction.SetCallback("Die",DeathMsg) | |
− | |||
− | |||
</pre> | </pre> | ||
+ | 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 :) | ||
== Tips and Tricks == | == Tips and Tricks == | ||
− | * To use dfusion's functionality in lua first run '' | + | * To use dfusion's functionality in lua first run ''dfusion'' (exit it with 'q') and then use run ''lua'' |
− |