Utility:DFHack/Programming - Revision history

Lethosor: fix links

2022-04-30T19:35:40Z

fix links

73.195.80.230: /* Simplest possible plugin: Hello world! */

2021-01-17T06:44:20Z

Simplest possible plugin: Hello world!

Choas: /* Getting DFHack */ adjust link to docs folder

2018-01-06T22:07:30Z

Getting DFHack: adjust link to docs folder

Mocha2007: /* Create your very own plugin */

2017-06-23T20:48:40Z

Create your very own plugin

2601:645:4200:BEB0:8D77:5A9D:625:C46A at 21:39, 2 February 2017

2017-02-02T21:39:49Z

2601:645:4200:BEB0:4EBB:58FF:FE5A:225C: Make signatures of plugin_init and plugin_shutdown clear.

2017-02-02T01:31:50Z

Make signatures of plugin_init and plugin_shutdown clear.

Lethosor: Undo revision 227228 by 1.36.75.208 (talk)

2016-10-02T19:26:01Z

Undo revision 227228 by 1.36.75.208 (talk)

OluapPlayer: Reverting vandalism

2016-10-02T11:55:05Z

Reverting vandalism

1.36.75.208: /* CHANGE LOG */

2016-10-02T03:36:33Z

CHANGE LOG

1.36.75.208: /* CHANGE LOG */

2016-10-02T03:35:52Z

CHANGE LOG

@@ Line 3: / Line 3: @@
 == INTRODUCTION ==
-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 ).
+DFHack is a Dwarf Fortress (DF) memory access library and a set of basic tools that use it (see the documentation at https://docs.dfhack.org/en/stable/ ).
 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 DFHack's low level functions very closely, and they will be able to perform complex functions ''very'' quickly.
-* Lua and Ruby scripts: text-based scripts which can be dropped into place and modified on the fly. Certain things can be easier to do, and error handling is better in general, but the downside is that they can be quite ''slow'' - for example, trying to reveal the entire map from Lua may take an entire minute, while the C++ plugin can do it in a tiny fraction of a second. This document is focused entirely on plugins - if you would like to learn more about writing scripts, see https://github.com/DFHack/dfhack/blob/master/Lua%20API.rst
+* Lua and Ruby scripts: text-based scripts which can be dropped into place and modified on the fly. Certain things can be easier to do, and error handling is better in general, but the downside is that they can be quite ''slow'' - for example, trying to reveal the entire map from Lua may take an entire minute, while the C++ plugin can do it in a tiny fraction of a second. This document is focused entirely on plugins - if you would like to learn more about writing scripts, see https://docs.dfhack.org/en/stable/docs/Lua%20API.html
 This document explains how to get started at writing C++ plugins with Microsoft Visual C++ 2010, step by step. It is intended for people who are totally new to DFHack.
@@ Line 20: / Line 20: @@
 You must download the sources, and build them.
-* Follow exactly the steps described in DFHack's readme: https://github.com/DFHack/dfhack/blob/master/docs/Compile.rst
+* Follow exactly the steps described in DFHack's documentation: https://docs.dfhack.org/en/stable/docs/Compile.html
 == Make yourself comfy ==

@@ Line 121: / Line 121: @@
+{
      out.print("Hello Monsieur Ouxx!\n");
+}
-return CR_OK;</pre>
+</pre>
 Please note that you have other outputs available:

@@ Line 20: / Line 20: @@
 You must download the sources, and build them.
-* Follow exactly the steps described in DFHack's readme: https://github.com/DFHack/dfhack/blob/master/Compile.rst
+* Follow exactly the steps described in DFHack's readme: https://github.com/DFHack/dfhack/blob/master/docs/Compile.rst
 == Make yourself comfy ==

@@ Line 47: / Line 47: @@
 Now you need to run DFHack's awesome build scripts, to make them generate all the relevant project files for you:
 * 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>
+* Run your favourite one. For example, you can choose <code>generate-MSVC-minimal.bat</code>
 Once this finishes, Visual C++ will prompt you to reload the project if you have it open, and once you do so you'll notice that your project "myplugin" has magically appeared. However, since the source file is still blank, it's not exactly ready to compile.

@@ Line 83: / Line 83: @@
 '''Note the <code>DFhackCExport</code> before the function signatures. This is required so that DFHack can load your plugin.'''
-The <code>color_ostream&</code> parameter to these functions is an output stream that prints to the DFHack console. You can use this to output debug messages when your plugin is being loaded/unloaded.
+The <code>color_ostream&</code> parameter to these functions is an output stream that prints to the DFHack console. You can use this to output debug messages when your plugin is being loaded/unloaded. (An example of using such an output stream is given in the section [http://dwarffortresswiki.org/index.php/Utility:DFHack/Programming#Simplest_possible_plugin:_Hello_world.21 Simplest possible plugin].)
 The second parameter to the <code>plugin_init</code> function is important -- it is a reference to the list of available commands. You use this to add your own command which calls the <code>myplugin</code> function you declared earlier.

@@ Line 79: / Line 79: @@
 ; Each plugin has two central functions:
-* <code>plugin_init</code>. This is run when the plugin gets loaded, whether or not its command gets run from the command line.
+* <code>DFhackCExport command_result plugin_init(color_ostream&, std::vector<PluginCommand>&)</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).
+* <code>DFhackCExport command_result plugin_shutdown(color_ostream)&</code>. This is run when the plugin gets unloaded (i.e. when DFHack shuts down).
-You'll notice that tubefill'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.
+'''Note the <code>DFhackCExport</code> before the function signatures. This is required so that DFHack can load your plugin.'''
-However, tubefill's <code>plugin_init</code> contains an important instruction, that will tell DFHack to be aware of a new custom command-line instruction:
+The <code>color_ostream&</code> parameter to these functions is an output stream that prints to the DFHack console. You can use this to output debug messages when your plugin is being loaded/unloaded.
-<pre>commands.push_back(PluginCommand("tubefill","Fill in all the adamantine tubes again.",tubefill, false,
+The second parameter to the <code>plugin_init</code> function is important -- it is a reference to the list of available commands. You use this to add your own command which calls the <code>myplugin</code> function you declared earlier.
-    "Replenishes mined out adamantine but does not fill hollow adamantine tubes.\n"
-    "Specify 'hollow' to fill hollow tubes, but beware glitchy HFS spawns.\n"));</pre>
+As an example, <code>tubefill</code> uses this code to add the "tubefill" command so it can be run in the console:
 Details:
@@ Line 93: / Line 101: @@
 * <code>tubefill</code> is the function that must be called when the command is typed into the command line.
 * <code>"Fill in all the adamantine tubes again."</code> and <code>"Replenishes mined out adamantine..."</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).
 Finally, you'll find the actual function definition:
@@ Line 98: / Line 109: @@
+{
      ...
+}
-return CR_OK;</pre>
+</pre>
 == Simplest possible plugin: Hello world! ==

@@ Line 278: / Line 278: @@
 == CHANGE LOG ==
-* v1.0 Redation
+* v1.0 Redaction
 * v1.1
 ** moved "return CR_OK;" in one of the code snippets
 ** corrected a mistake about the need of using "DEFINE_VMETHOD_INTERPOSE"

← Older revision		Revision as of 11:55, 2 October 2016
Line 282:		Line 282:
	** moved "return CR_OK;" in one of the code snippets		** moved "return CR_OK;" in one of the code snippets
	** corrected a mistake about the need of using "DEFINE_VMETHOD_INTERPOSE"		** corrected a mistake about the need of using "DEFINE_VMETHOD_INTERPOSE"
−	** FUCK YOU FUCK YOU

← Older revision		Revision as of 03:36, 2 October 2016
Line 282:		Line 282:
	** moved "return CR_OK;" in one of the code snippets		** moved "return CR_OK;" in one of the code snippets
	** corrected a mistake about the need of using "DEFINE_VMETHOD_INTERPOSE"		** corrected a mistake about the need of using "DEFINE_VMETHOD_INTERPOSE"
		+	** FUCK YOU FUCK YOU