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:DFHack/Programming
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: | ||
<pre>v1.1 (see change log at the end)</pre> | <pre>v1.1 (see change log at the end)</pre> | ||
+ | |||
== INTRODUCTION == | == INTRODUCTION == | ||
− | DFHack is a Dwarf Fortress (DF) memory access library and a set of basic tools that use it (see the | + | DFHack is a Dwarf Fortress (DF) memory access library and a set of basic tools that use it (see the readme at https://github.com/DFHack/dfhack/blob/master/Readme.rst ). |
− | It is possible for developers to write plugins for DFHack, in order to extend the capabilities of DFHack (and therefore | + | It is possible for developers to write plugins for DFHack, in order to extend the capabilities of DFHack (and therefore DF’s gameplay). The plugins come mainly in two flavours: |
− | * C++ plugins: libraries written in C++ that need to be compiled. They can use | + | * C++ plugins: libraries written in C++, that need to be compiled. They can use DFHack’s low level functions very closely. |
− | * Lua and Ruby scripts: | + | * Lua and Ruby scripts: placed in the right folder, they are loaded at DFHack’s startup (outside of this document’s scope. see more at https://github.com/DFHack/dfhack/blob/master/Lua%20API.rst ) |
− | This document explains how to get started at writing C++ plugins with | + | This document explains how to get started at writing C++ plugins with VisualC++ 2010, step by step. It is intended for people who are totally new to DFHack. |
== Getting Dwarf Fortress == | == Getting Dwarf Fortress == | ||
− | + | You’ll need a test environment to run your script. Hence the need of getting DF. I’d recommend getting the latest “Lazy Newb Pack”, which includes not only Dwarf Fortress but also DFHack and other nice things, ready-to-use: | |
− | * Download the latest | + | <blockquote> |
+ | * Download the latest “Lazy Newb Pack”. | ||
+ | </blockquote> | ||
You can run DF once and observe the DFHack console. Type <code>die</code> in that window to observe that the command line works (<code>die</code> is a command to force-close DF). | You can run DF once and observe the DFHack console. Type <code>die</code> in that window to observe that the command line works (<code>die</code> is a command to force-close DF). | ||
Line 20: | Line 23: | ||
You must download the sources, and build them. | You must download the sources, and build them. | ||
− | * Follow exactly the steps described in | + | <blockquote> |
+ | * Follow exactly the steps described in DFHack’s readme : https://github.com/DFHack/dfhack/blob/master/Compile.rst | ||
+ | </blockquote> | ||
== Make yourself comfy == | == Make yourself comfy == | ||
− | + | ||
− | As explained in the compiling guidelines (above), there are several scripts available, that will do different things : some will just build, some will also install the results to your | + | As explained in the compiling guidelines (above), there are several scripts available, that will do different things : some will just build, some will also install the results to your DF’s DFHack folder. To save some time, here is to run the latter script in your VisualC++ every time you press <code>F7</code> (Generate solution): |
− | * Open <code>dfhack.sln</code> in | + | <blockquote> |
− | * Right-click on the Solution, and select | + | * Open <code>dfhack.sln</code> in VisualC++ |
− | * Go to | + | * Right-click on the Solution, and select “Properties” |
+ | * Go to “configuration properties”–>“Configuration” | ||
* In the full list of projects, uncheck <code>ALL_BUILD</code>, and instead check <code>INSTALL</code> | * In the full list of projects, uncheck <code>ALL_BUILD</code>, and instead check <code>INSTALL</code> | ||
+ | </blockquote> | ||
+ | This way, it will force-build “INSTALL” every time. And guess what? That runs the install script. | ||
== Create your very own plugin == | == Create your very own plugin == | ||
+ | |||
; What are the requirements for a plugin? | ; What are the requirements for a plugin? | ||
− | * | + | <blockquote> |
− | * The libraries (<code>.lib</code>) it will use | + | ;* Its set of C++ source files (there can be just one if you want!) |
− | * The protobufs it will use (if any!) | + | ;* The libraries (<code>.lib</code>) it will use |
− | + | ;* The protobufs it will use (if any!) | |
+ | </blockquote> | ||
+ | Protobufs are some sort of serialization standard developed by Google. This is outside of the scope of this document. Only a handful of plugins use that technology. The <code>rename</code> and <code>isoworldremote</code> plugins do. | ||
− | The libraries are all the 3rd-party libraries you want to use in your project. The good news is that most libraries normally used in C++ have a high probability to be already used by some other plugin | + | The libraries are all the 3rd-party libraries you want to use in your project. The good news is that most libraries normally used in C++ have a high probability to be already used by some other plugin. |
+ | ; For example: | ||
+ | <blockquote> | ||
+ | ;* <code>workflow</code> links to <code>Lua</code>. | ||
+ | ;* <code>dfstream</code> links to <code>dfhack-tinythread</code>. | ||
+ | ;* I believe I’ve seen a plugin using <code>boost</code>. | ||
+ | ;* <code>SDL</code> is available in any case. | ||
+ | </blockquote> | ||
; The first step is to add your plugin to the list of plugins : | ; The first step is to add your plugin to the list of plugins : | ||
− | * Open <code>dfhack/plugins/CMakeLists.txt</code> | + | <blockquote> |
− | * Locate the section listing all the plugins : they start with <code>DFHACK_PLUGIN</code> | + | ;* Open <code>dfhack/plugins/CMakeLists.txt</code> |
− | * Add a line with your own plugin: <code>DFHACK_PLUGIN(myplugin myplugin.cpp)</code>, and save the file. | + | ;* Locate the section listing all the plugins : they start with <code>DFHACK_PLUGIN</code> |
− | * Create a blank file called <code>myplugin.cpp</code> in <code>dfhack/plugins</code>, alongside all the other plugins | + | ;* Add a line with your own plugin: <code>DFHACK_PLUGIN(myplugin myplugin.cpp)</code> , and save the file. |
+ | ;* Create a blank file called <code>myplugin.cpp</code> in <code>dfhack/plugins</code> , alongside all the other plugins | ||
+ | </blockquote> | ||
+ | Now you need to run DFHack’s awesome build scripts, to make them generate all the relevant project files for you: | ||
+ | <blockquote> | ||
+ | * Close VisualStudio | ||
+ | * Observe all the batch files in <code>dfhack/build</code> starting with “generate” | ||
+ | * Run your favourite one. For example you can choose <code>generate-MSVC-minimal.bat</code> | ||
+ | </blockquote> | ||
+ | Now if you re-open <code>dfhack.sln</code> (in <code>dfhack/build/VC2010/</code>) , you’ll notice that your project “myplugin” has magically appeared. But its’ not ready to compile yet! (the source file is empty, dummy) | ||
− | + | == Mandatory C++ instructions == | |
− | |||
− | |||
− | |||
− | + | Open any simple plugin (e.g. <code>catsplosion.cpp</code> ) and observe its structure. | |
− | + | You’ll notice all the includes for using standard data structures (lists, vectors, etc.) : | |
− | + | <pre>#include <iostream> | |
+ | #include <cstdlib> | ||
+ | #include <assert.h> | ||
+ | #include <climits> | ||
+ | #include <stdlib.h> // for rand() | ||
+ | #include <algorithm> // for std::transform | ||
+ | #include <vector> | ||
+ | #include <list> | ||
+ | #include <iterator> | ||
+ | using namespace std;</pre> | ||
+ | More interestingly, you’ll notice all the includes allowing you to use DFHack: | ||
− | <pre>#include | + | <pre>#include "DFHack.h" |
− | #include | + | #include "Core.h" |
− | #include | + | #include "Console.h" |
− | #include | + | #include "Export.h" |
− | #include | + | #include "PluginManager.h" |
+ | #include "DataDefs.h" | ||
using namespace DFHack;</pre> | using namespace DFHack;</pre> | ||
+ | Let’s imagine your plugin will be a command called from DFHack’s console. Well then, that command will call an actual function. It is that function that you declare here: | ||
− | + | <pre>command_result catsplosion (color_ostream &out, std::vector <std::string> & parameters);</pre> | |
− | + | For now, the function only gets declared, we’ll define it later in the source code. You’ll need to do the same, by replacing <code>catsplosion</code> with <code>myplugin</code> | |
− | |||
− | |||
− | <pre>command_result | ||
− | |||
− | For now, the function only gets declared, | ||
− | <code>myplugin</code> | ||
− | Now, tell | + | Now, tell DFHack’s global plugin engine to be aware of our plugin (so that it can load it, etc.): |
− | <pre>DFHACK_PLUGIN( | + | <pre>DFHACK_PLUGIN("catsplosion");</pre> |
− | From now on, every time you see | + | From now on, every time you see “catsplosion”, replace it with “myplugin”. |
; Each plugin has two central functions: | ; Each plugin has two central functions: | ||
− | * <code> | + | <blockquote> |
− | * <code> | + | * <code>plugin_init</code>. This is run when the plugin gets loaded, whether or not its command gets run from the command line. |
− | + | * <code>plugin_shutdown</code>. This is run when the plugin gets unloaded (i.e. when DFHack shuts down). | |
− | + | </blockquote> | |
− | + | You’ll notice that catsplosion’s <code>plugin_shutdown</code> is empty (it just returns the standardized “OK” return code : <code>CR_OK</code>). That’s because the plugin is simple and doesn’t need to delete objects, or close connections, or do any kind of post-processing. | |
− | |||
− | |||
− | + | However, catsplosion’s <code>plugin_init</code> contains an important instruction, that will tell DFHack to be aware of a new custom command-line instruction: | |
− | <pre> | + | <pre>// Fill the command list with your commands. |
− | + | commands.push_back(PluginCommand( | |
− | + | "catsplosion", "Make cats just /multiply/.", | |
− | + | catsplosion, false, | |
− | + | " Makes cats abnormally abundant, if you provide some base population ;)\n" | |
− | + | ));</pre> | |
− | |||
Details: | Details: | ||
− | * <code> | + | <blockquote> |
− | * <code> | + | * <code>"catsplosion"</code> will be the string to which the command line must respond ,when entered. |
− | * <code> | + | * <code>catsplosion</code> is the function that must be called when the command is typed intot he command line. |
+ | * <code>"Make cats just multiply"</code> and <code>"Make cats abnormally ..."</code> are the “manual” that will be displayed in the help or when the command is called with the wrong parameters (see below how to test that). | ||
+ | </blockquote> | ||
+ | Finally, you’ll find the actual function definition: | ||
− | + | <pre>command_result catsplosion (color_ostream &out, std::vector <std::string> & parameters) | |
− | |||
− | |||
− | |||
− | <pre>command_result | ||
{ | { | ||
... | ... | ||
− | |||
} | } | ||
− | </pre> | + | return CR_OK;</pre> |
− | |||
− | |||
== Simplest possible plugin: Hello world! == | == Simplest possible plugin: Hello world! == | ||
Line 120: | Line 143: | ||
<pre>command_result myplugin (color_ostream &out, std::vector <std::string> & parameters) | <pre>command_result myplugin (color_ostream &out, std::vector <std::string> & parameters) | ||
{ | { | ||
− | out.print( | + | out.print("Hello Monsieur Ouxx!\n"); |
− | |||
} | } | ||
− | </pre> | + | return CR_OK;</pre> |
Please note that you have other outputs available: | Please note that you have other outputs available: | ||
− | <pre>out.printerr( | + | <pre>out.printerr("Oh my gosh, this is an error.\n");</pre> |
− | You can now test your plugin : Press F7, then run DF and enter | + | You can now test your plugin : Press F7, then run DF and enter “myplugin” in the DFHack console. You should see the message “Hello Monsieur Ouxx!”. |
== Parameters checking == | == Parameters checking == | ||
Line 138: | Line 160: | ||
for(size_t i = 0; i < parameters.size();i++) | for(size_t i = 0; i < parameters.size();i++) | ||
{ | { | ||
− | if(parameters[i] == | + | if(parameters[i] == "param1") |
param1_ok = true; | param1_ok = true; | ||
− | else if(parameters[i] == | + | else if(parameters[i] == "param2") |
param2_ok = true; | param2_ok = true; | ||
else | else | ||
Line 152: | Line 174: | ||
As explained before, if <code>CR_WRONG_USAGE</code> is returned, then the verbose help text defined in <code>commands.push_back</code> will be displayed. | As explained before, if <code>CR_WRONG_USAGE</code> is returned, then the verbose help text defined in <code>commands.push_back</code> will be displayed. | ||
− | Another interesting approach to that (as seen in plugin | + | Another interesting approach to that (as seen in plugin “buildingplan”): |
<pre>if (!parameters.empty()) | <pre>if (!parameters.empty()) | ||
Line 158: | Line 180: | ||
if (parameters.size() == 1 && toLower(parameters[0])[0] == 'v') | if (parameters.size() == 1 && toLower(parameters[0])[0] == 'v') | ||
{ | { | ||
− | out << | + | out << "Building Plan" << endl << "Version: " << PLUGIN_VERSION << endl; |
} | } | ||
− | else if (parameters.size() == 2 && toLower(parameters[0]) == | + | else if (parameters.size() == 2 && toLower(parameters[0]) == "debug") |
{ | { | ||
− | show_debugging = (toLower(parameters[1]) == | + | show_debugging = (toLower(parameters[1]) == "on"); |
− | out << | + | out << "Debugging " << ((show_debugging) ? "enabled" : "disabled") << endl; |
} | } | ||
}</pre> | }</pre> | ||
− | == Suspend the core! == | + | == Suspend the core!!!!!111!!11 == |
− | This might be the MOST IMPORTANT section in this document. Never ever forget to suspend the | + | This might be the MOST IMPORTANT section in this document. Never ever forget to suspend the game’s core execution before you manipulate anything in its internal data. It is done by running the following instruction: |
<pre>CoreSuspender suspend;</pre> | <pre>CoreSuspender suspend;</pre> | ||
+ | You will observe that most plugins actually start with that instruction. Fortunately, our “Hello world” plugin doesn’t manipulate any internal data, so we didn’t need that. But that’s about to change. | ||
− | + | == Create your own view screen == | |
− | + | Many plugins consist in adding menus to DF in order to extend capabilities (or, at least, sort out DF’s mess ;) ). | |
− | + | A good example of that is plugin <code>buildingplan</code>. It displays a menu with lists of materials, and allows to filter the materials. Lists and filters. That’s what DF is all about! ;) | |
− | + | http://imageshack.us/a/img28/4686/materials.png | |
− | + | You make them fit into a “view screen”, that is: an additional screen that will fit into DF. This section is about creating a NEW viewscreen, not replacing one already existing in DF. | |
− | |||
− | You make them fit into a | ||
Have a look at class <code>ViewscreenChooseMaterial</code> : it extends DFHack-provided class <code>dfhack_viewscreen</code>: | Have a look at class <code>ViewscreenChooseMaterial</code> : it extends DFHack-provided class <code>dfhack_viewscreen</code>: | ||
Line 205: | Line 226: | ||
Notice how <code>render</code> calls the overridden function of its parent class. | Notice how <code>render</code> calls the overridden function of its parent class. | ||
− | You will find more examples in | + | You will find more examples in plugin <code>manipulator</code>. Have a look at class <code>viewscreen_unitlaborsst</code> |
− | See also: | + | See also: “Replacing an existing view screen” |
== Manipulate the display == | == Manipulate the display == | ||
− | Once your | + | Once your view screen is up and running, with its very own <code>render</code> function, you may do whatever you please with the display: |
<pre>Screen::clear(); //delete the screen | <pre>Screen::clear(); //delete the screen | ||
− | Screen::drawBorder( | + | Screen::drawBorder(" Building Material "); //create a new DF-stryle screen, with a title and a border |
masks_column.display(selected_column == 0); //display our column (read this tutorial further) | masks_column.display(selected_column == 0); //display our column (read this tutorial further) | ||
int32_t y = gps->dimy - 3; //do some calculation on the window size, to position stuff | int32_t y = gps->dimy - 3; //do some calculation on the window size, to position stuff | ||
− | OutputHotkeyString(2, y, | + | OutputHotkeyString(2, y, "Toggle", "Enter"); //define some hotkey |
x += 3; | x += 3; | ||
− | OutputHotkeyString(x, y, | + | OutputHotkeyString(x, y, "Save", "Shift-Enter");</pre> |
+ | == List columns == | ||
− | + | In class <code>ViewscreenChooseMaterial</code> ’s private members, you’ll see this: | |
− | In class <code>ViewscreenChooseMaterial</code> | ||
<pre>ListColumn<df::dfhack_material_category> masks_column;</pre> | <pre>ListColumn<df::dfhack_material_category> masks_column;</pre> | ||
− | |||
<code>ListColumn</code> is a template provided by DFHack. Just feed it with anything you like. | <code>ListColumn</code> is a template provided by DFHack. Just feed it with anything you like. | ||
− | == Manipulating | + | == Manipulating DF’s data == |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | Start with observing class <code>ItemFilter</code>. You’ll notice that DF exposes pretty much every possible type of object/item from the game. And what DF doesn’t, DFHack does. You’ll immediately notice these:: df::dfhack_material_category DFHack::MaterialInfo df::enums::item | ||
+ | <blockquote>etc. | ||
+ | </blockquote> | ||
Have a look at <code>vector<string> getMaterialFilterAsVector()</code>. It shows you how to get the description from a material, as a string: | Have a look at <code>vector<string> getMaterialFilterAsVector()</code>. It shows you how to get the description from a material, as a string: | ||
Line 244: | Line 261: | ||
if (descriptions.size() == 0) | if (descriptions.size() == 0) | ||
bitfield_to_string(&descriptions, mat_mask);</pre> | bitfield_to_string(&descriptions, mat_mask);</pre> | ||
+ | <blockquote> | ||
== Managing speed == | == Managing speed == | ||
Line 262: | Line 280: | ||
}</pre> | }</pre> | ||
− | == | + | == Replacing an existing view screen == |
− | Maybe you | + | </blockquote> |
+ | Maybe you don’t want to add an additional view screen, but instead add features to one that already exists in DF. In that case, creating a child to <code>dfhack_viewscreen</code>` (as seen in section “Create your own view screen”) and overriding <code>render</code> and <code>feed</code> is not enough. You need to “interpose” those two functions in the global DF system. | ||
− | + | That’s the case of class <code>buildingplan_hook</code> in plugin <code>buildingplan</code>. | |
You will notice that, unlike <code>ViewscreenChooseMaterial</code>, it extends class <code>df::viewscreen_dwarfmodest</code> instead of <code>dfhack_viewscreen</code>: | You will notice that, unlike <code>ViewscreenChooseMaterial</code>, it extends class <code>df::viewscreen_dwarfmodest</code> instead of <code>dfhack_viewscreen</code>: | ||
Line 276: | Line 295: | ||
{ | { | ||
... | ... | ||
− | |||
DEFINE_VMETHOD_INTERPOSE(void, render, ()) | DEFINE_VMETHOD_INTERPOSE(void, render, ()) | ||
Line 282: | Line 300: | ||
... | ... | ||
}</pre> | }</pre> | ||
− | Once | + | Once you’ve defined how the two functions will insert into DF, you can put them to action: |
<pre>IMPLEMENT_VMETHOD_INTERPOSE(buildingplan_hook, feed); | <pre>IMPLEMENT_VMETHOD_INTERPOSE(buildingplan_hook, feed); | ||
IMPLEMENT_VMETHOD_INTERPOSE(buildingplan_hook, render);</pre> | IMPLEMENT_VMETHOD_INTERPOSE(buildingplan_hook, render);</pre> | ||
+ | Note: That would need more explanations. | ||
− | + | See also: “Create your own view screen” | |
− | |||
− | See also: | ||
== CHANGE LOG == | == CHANGE LOG == | ||
+ | <blockquote> | ||
* v1.0 Redaction | * v1.0 Redaction | ||
* v1.1 | * v1.1 | ||
− | ** moved | + | ** moved “return CR_OK;” in one of the code snippets |
− | ** corrected a mistake about the need of using | + | ** corrected a mistake about the need of using “DEFINE_VMETHOD_INTERPOSE” |
+ | </blockquote> |