Editing Utility:DFusion

== DFusion info page ==
Thread for discussions: [http://www.bay12forums.com/smf/index.php?topic=93317.0 Thread]
== Usage ==
Dfusion plugin offers four DFhack commands: 'dfusion', 'dfuse' and 'lua', 'runlua'.
=== 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.
=== runlua ===
Similar to ''lua <filename>'' but not interactive, to be used with hotkeys
=== dfusion ===
First this command runs all plugins' init.lua part then show a menu. Type number to run specified plugin.
=== dfuse ===
Similar to dfusion but not interactive. To be used with hotkeys (later will have command support).


Also dfuse/dfusion runs an init script located at 'save directory/dfusion/init.lua'. And 'initcustom.lua' if it exists

== Exported functions and objects ==
The DF is accessed by object 'df'. This object holds all the types, globals table and some helper functions.
Up-to-date api help could be found here: https://github.com/peterix/dfhack/blob/master/LUA_API.rst
=== Examples ===
<pre>
first_unit=df.global.world.units.all[0] --gets first unit
first_unit.name.first_name="Urist"
</pre>
You can iterate in all the objects:
<pre>
for k,v in pairs(df.global.world.units.all) do --gets ALL the units
   v.name.first_name="Urist" --now everyone will be called URIST!!
end
</pre>
Also all the flags can be accessed by name or by number:
<pre>
first_unit.flags.dead=true --is same as...
first_unit.flags[1]=true --... this
</pre>
For convienence there is function printall:
<pre>
printall(df.global.world.units.all) --prints all the units, with locations in memory
</pre>
=== Other objects ===
==== Console. ====
{| class="wikitable"
|-
! name
! description
! example
|-
| print
| prints a message to dfhack console
| Console.print("Hello world!")
|-
| printerr
| prints an error message to dfhack console
| Console.printerr("Error  world!")
|-
| clear
| clears console
| Console.clear()
|-
| color
| sets text color
| Console.color(2)
|-
| reset_color
| resets text color to defaults
| Console.reset_color()
|-
| cursor
| sets if the cursor should be visible
| Console.cursor(true)
|-
| msleep
| waits for x milliseconds 
| Console.msleep(200)
|-
| get_columns
| returns number of columns in the console
| Console.get_columns()
|-
| get_rows
| returns number of rows in the console
| Console.get_rows()
|-
| lineedit
| asks user for input
| Console.lineedit("Type in your name:")
|}
==== Process. ====
==== VersionInfo. ====
==== engine. ====
{| class="wikitable"
|-
! name
! description
! example
|-
| peek(b\w\d)
| reads byte\word\double word from memory
| peekb(0x15486)
|-
| peekarb
| reads a chunk of memory
| peekarb(0x15486,100) -- reads 100 bytes from 0x15486
|-
| peekstr
| reads a string from memory
| peekstr(0x15486) 
|-
| poke(b\w\d)
| writes byte\word\double word to memory
| peekb(0x15486,100)
|-
| pokearb
| writes a chunk of memory (gotten with peekarb)
| pokearb(0x15486,data,100) -- writes 100 bytes from data to 0x15486
|-
| pokestr
| writes a string to memory
| peekstr(0x15486,"Hello world") 
|}

==== FunctionCall.====
{| class="wikitable"
|-
! name
! description
! example
|-
| call(f_ptr,calling_convention,arguments...)
| calls a function from df. Supports up to 7 arguments. Danger: this could (and probably will) crash df if used incorrectly.
| FunctionCall.call(somepointertofunction,FunctionCall.THIS_CALL,thisptr)
|-
| THIS_CALL
| a numeric constant for function calling convention. 
| -
|-
| STD_CALL
| -"-
| -
|-
| FAST_CALL
| -"-
| -
|-
| CDECL_CALL
| -"-
| -
|}

=== From scripts ===
These commands are exported from script files. Most of them are in "common.lua" file.
=== Patterns ===
DEPRECATED use df.<subitem>

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

Individual units can be modified - skills, jobs, attributes, etc. This example selects a unit under the look cursor, updates the name and updates the level and experience for selected skills. 
<pre>
--Takes a selected unit and instantly turns them into Morul - upgrading all appropriate skills to Legendary or higher, as appropriate
--By Martin, 5/25/2012, excerpt for demonstration purposes
--This code gets cut/pasted at the end of /dfusion/tools/init.lua
function tools.morul(unit)
  --include the utils library which we need later
  utils = require 'utils'
  --a unit address can be passed into this function, handle the case where one isn't
  if unit==nil then
    unit=getCreatureAtPointer()  --place the x pointer on top of the creature you want to change. best use is the look pointer 'k' and not 'v'
  end
  --Set the name. Surname is comprised of an array of references [words] into the language file. Each entry grabs a word fragment and the name is all of these catenated 
  unit.name.first_name = "Morul"
  unit.name.words[0] = 1416  --[T_WORD:CHANNEL:catten]
  unit.name.words[1] = 1304  --[T_WORD:BEND:mat]

  --skill level we wish to apply to all labors. Dabbling is 0, Legendary is 15
  labor_rating = 15
  --the skill level we wish to apply to all military skills. 
  military_rating = 70
  
  --These are the skill ids we want to add. The ids were identified in game_data.ini in DwarfTherapist.
  skill = { 0,2,3,4,5,6,7,8,9,10,11,12,13,14,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,41,42,43,44,45,46,47,48,49,54,55,57,58,59,60,61,62,63,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,95,96,97,98,99,100,101,102,103,104,105,109,110,111,112,113,114,115 }
  --These are the military skills that will get higher values. Subset of the list above.
  military = { 38,39,41,42,43,44,45,46,54,99,100,101,102,103,104,105 }

  --ipairs iterates over each indexed item in the skill list. Lua index is 1 based, so remember that.
  for sk,sv in ipairs(skill) do
    --assume the labor rating will apply
    new_rating = labor_rating
    --iterate over the military list
    for _,v in ipairs(military) do
      --if the value from the skill list iteration is in the military list...
      if v == sv then
        --then use the military skill level
        new_rating = military_rating
      end
    end
    --the skills need to be inserted in a particular way. This standard function passes the id, the skill level, and the experience value, and tells the tool to keep the skills sorted by id. 
    --the experience calculation reflects the minimum experience to earn the level and allows skills to continue to advance.
    utils.insert_or_update(unit.status.current_soul.skills, { new = true, id = sv, rating = new_rating, experience = (new_rating * 500) + (new_rating * (new_rating - 1)) * 50}, 'id')
  end
  
  -- walk over each of the skills we just set and print them out so we can confirm each update
  for sk,sv in ipairs(unit.status.current_soul.skills) do
    -- print the skill data. Printall will print entire tables and is handy at poking at the data structures
    printall(sv)
  end
end

--add the function above to the dfusion menu system as a submenu under the 'Tools' menu.
tools.menu:add("Morul",tools.morul)
</pre>

== Tips and Tricks ==
* To use dfusion's functionality in lua first run ''dfuse'' and then use run ''lua''
* You can bind keys to lua commands (in dfusion context) like this: ''keybindings add Shift-R "dfuse adv_tools.reincarnate()"''