MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improves plugin dev documentation through updating skeleton.cpp

develop
Josh Cooper 2021-07-03 19:32:02 -07:00 committed by Myk
parent 48444afbd5
commit 051e891680
1 changed files with 84 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
plugins/skeleton/skeleton.cpp
Unescape Escape View File

@ -5,7 +5,7 @@
#include <Console.h> #include <Console.h>
#include <Export.h> #include <Export.h>
#include <PluginManager.h> #include <PluginManager.h>
#include <modules/EventManager.h>
// If you need to save data per-world: // If you need to save data per-world:
//#include "modules/Persistence.h" //#include "modules/Persistence.h"
@ -19,94 +19,114 @@
using namespace DFHack; using namespace DFHack;
using namespace df::enums; using namespace df::enums;
// Expose the plugin name to the DFHack core, as well as metadata like the DFHack version. // A plugin must be able to return its name and version.
// The name string provided must correspond to the filename - // The name string provided must correspond to the filename -
// skeleton.plug.so, skeleton.plug.dylib, or skeleton.plug.dll in this case // skeleton.plug.so, skeleton.plug.dylib, or skeleton.plug.dll in this case
DFHACK_PLUGIN("skeleton"); DFHACK_PLUGIN("skeleton");
// A plugin can have a state which can be used to manage how the plugin operates.
// The state is referred to by this the identifier provided to the macro. eg. `enabled`
DFHACK_PLUGIN_IS_ENABLED(enabled);
// Any globals a plugin requires (e.g. world) should be listed here. // Any globals a plugin requires (e.g. world) should be listed here.
// For example, this line expands to "using df::global::world" and prevents the // For example, this line expands to "using df::global::world" and prevents the
// plugin from being loaded if df::global::world is null (i.e. missing from symbols.xml): // plugin from being loaded if df::global::world is null (i.e. missing from symbols.xml):
// //
// REQUIRE_GLOBAL(world); REQUIRE_GLOBAL(world);
// Here go all the command declarations... // You may want some compile time debugging options
// mostly to allow having the mandatory stuff on top of the file and commands on the bottom // one easy system just requires you to cache the color_ostream &out into a global debug variable
command_result skeleton (color_ostream &out, std::vector <std::string> & parameters); //#define P_DEBUG 1
//uint16_t maxTickFreq = 1200; //maybe you want to use some events
// Mandatory init function. If you have some global state, create it here.
DFhackCExport command_result plugin_init (color_ostream &out, std::vector <PluginCommand> &commands) command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters);
{
// Fill the command list with your commands. DFhackCExport command_result plugin_init(color_ostream &out, std::vector<PluginCommand> &commands) {
commands.push_back(PluginCommand( commands.push_back(PluginCommand("skeleton",
"skeleton", "Do nothing, look pretty.", "~54 character description of plugin", //to use one line in the ``[DFHack]# ls`` output
skeleton, false, /* true means that the command can't be used from non-interactive user interface */ command_callback1,
// Extended help string. Used by CR_WRONG_USAGE and the help command: false,
" This command does nothing at all.\n" ""
"Example:\n" " skeleton <option> <args>\n"
" skeleton\n" " explanation of plugin/command\n"
" Does nothing.\n" "\n"
)); " skeleton\n"
" what happens when using the command\n"
"\n"
" skeleton option1\n"
" what happens when using the command with option1\n"
"\n"));
return CR_OK; return CR_OK;
} }
// This is called right before the plugin library is removed from memory. DFhackCExport command_result plugin_shutdown(color_ostream &out) {
DFhackCExport command_result plugin_shutdown (color_ostream &out)
{
// You *MUST* kill all threads you created before this returns. // You *MUST* kill all threads you created before this returns.
// If everything fails, just return CR_FAILURE. Your plugin will be // If everything fails, just return CR_FAILURE. Your plugin will be
// in a zombie state, but things won't crash. // in a zombie state, but things won't crash.
return CR_OK; return CR_OK;
} }
// Used by `plug` to track this plugin's status.
// Called to enable/disable this plugin's state.
// Is called when using `enable` or `disable` in the console
/*
DFHACK_PLUGIN_IS_ENABLED(enabled);
DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) { DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
namespace EM = EventManager;
if (enable && !enabled) {
//using namespace EM::EventType;
//EM::EventHandler eventHandler(onNewEvent, maxTickFreq);
//EM::registerListener(EventType::JOB_COMPLETED, eventHandler, plugin_self);
//out.print("plugin enabled!\n");
} else if (!enable && enabled) {
EM::unregisterAll(plugin_self);
//out.print("plugin disabled!\n");
}
enabled = enable; enabled = enable;
// other code
return CR_OK; return CR_OK;
} }
*/
/* OPTIONAL *
// Called to notify the plugin about important state changes. // Called to notify the plugin about important state changes.
// Invoked with DF suspended, and always before the matching plugin_onupdate. // Invoked with DF suspended, and always before the matching plugin_onupdate.
// More event codes may be added in the future. // More event codes may be added in the future.
/* DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) if (enabled) {
{ switch (event) {
switch (event) { case SC_UNKNOWN:
case SC_GAME_LOADED: break;
// initialize from the world just loaded case SC_WORLD_LOADED:
break; break;
case SC_GAME_UNLOADED: case SC_WORLD_UNLOADED:
// cleanup break;
break; case SC_MAP_LOADED:
default: break;
break; case SC_MAP_UNLOADED:
break;
case SC_VIEWSCREEN_CHANGED:
break;
case SC_CORE_INITIALIZED:
break;
case SC_BEGIN_UNLOAD:
break;
case SC_PAUSED:
break;
case SC_UNPAUSED:
break;
}
} }
return CR_OK; return CR_OK;
} }
*/
// Whatever you put here will be done in each game step. Don't abuse it. // Whatever you put here will be done in each game step. Don't abuse it.
// It's optional, so you can just comment it out like this if you don't need it.
/*
DFhackCExport command_result plugin_onupdate ( color_ostream &out ) DFhackCExport command_result plugin_onupdate ( color_ostream &out )
{ {
// whetever. You don't need to suspend DF execution here. // whetever. You don't need to suspend DF execution here.
return CR_OK; return CR_OK;
} }
*/
// If you need to save or load world-specific data, define these functions. // If you need to save or load world-specific data, define these functions.
// plugin_save_data is called when the game might be about to save the world, // plugin_save_data is called when the game might be about to save the world,
// and plugin_load_data is called whenever a new world is loaded. If the plugin // and plugin_load_data is called whenever a new world is loaded. If the plugin
// is loaded or unloaded while a world is active, plugin_save_data or // is loaded or unloaded while a world is active, plugin_save_data or
// plugin_load_data will be called immediately. // plugin_load_data will be called immediately.
/*
DFhackCExport command_result plugin_save_data (color_ostream &out) DFhackCExport command_result plugin_save_data (color_ostream &out)
{ {
// Call functions in the Persistence module here. // Call functions in the Persistence module here.
@ -118,26 +138,33 @@ DFhackCExport command_result plugin_load_data (color_ostream &out)
// Call functions in the Persistence module here. // Call functions in the Persistence module here.
return CR_OK; return CR_OK;
} }
*/ * OPTIONAL */
// A command! It sits around and looks pretty. And it's nice and friendly. // A command! It sits around and looks pretty. And it's nice and friendly.
command_result skeleton (color_ostream &out, std::vector <std::string> & parameters) command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters) {
{
// It's nice to print a help message you get invalid options // It's nice to print a help message you get invalid options
// from the user instead of just acting strange. // from the user instead of just acting strange.
// This can be achieved by adding the extended help string to the // This can be achieved by adding the extended help string to the
// PluginCommand registration as show above, and then returning // PluginCommand registration as show above, and then returning
// CR_WRONG_USAGE from the function. The same string will also // CR_WRONG_USAGE from the function. The same string will also
// be used by 'help your-command'. // be used by 'help your-command'.
if (!parameters.empty()) if (!parameters.empty()) {
return CR_WRONG_USAGE; return CR_WRONG_USAGE; //or maybe you want it to do something else
}
// Commands are called from threads other than the DF one. // Commands are called from threads other than the DF one.
// Suspend this thread until DF has time for us. If you // Suspend this thread until DF has time for us.
// use CoreSuspender, it'll automatically resume DF when // **If you use CoreSuspender** it'll automatically resume DF when
// execution leaves the current scope. // execution leaves the current scope.
CoreSuspender suspend; CoreSuspender suspend;
// Actually do something here. Yay. // Actually do something here. Yay.
out.print("Hello! I do nothing, remember?\n");
// process parameters
if (parameters.size() == 1 && parameters[0] == "option1") {
// stuff
} else {
return CR_FAILURE;
}
// Give control back to DF. // Give control back to DF.
return CR_OK; return CR_OK;
} }