From 2f9021a3a0911d1cd39108535e02b91f4abb8db3 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Tue, 2 Aug 2022 12:56:44 -0700
Subject: [PATCH 1/9] move examples to the examples folder

---
 docs/Dev-intro.rst                            |  4 +--
 plugins/CMakeLists.txt                        |  6 ----
 plugins/{skeleton => examples}/skeleton.cpp   |  0
 .../{skeleton => examples}/skeletonShort.cpp  |  0
 plugins/skeleton/CMakeLists.txt               | 36 -------------------
 plugins/skeleton/skeleton.h                   |  1 -
 6 files changed, 2 insertions(+), 45 deletions(-)
 rename plugins/{skeleton => examples}/skeleton.cpp (100%)
 rename plugins/{skeleton => examples}/skeletonShort.cpp (100%)
 delete mode 100644 plugins/skeleton/CMakeLists.txt
 delete mode 100644 plugins/skeleton/skeleton.h

diff --git a/docs/Dev-intro.rst b/docs/Dev-intro.rst
index 758bf225f..d4167aae3 100644
--- a/docs/Dev-intro.rst
+++ b/docs/Dev-intro.rst
@@ -22,7 +22,7 @@ Plugins
 
 DFHack plugins are written in C++ and located in the ``plugins`` folder.
 Currently, documentation on how to write plugins is somewhat sparse. There are
-templates that you can use to get started in the ``plugins/skeleton``
+templates that you can use to get started in the ``plugins/examples``
 folder, and the source code of existing plugins can also be helpful.
 
 If you want to compile a plugin that you have just added, you will need to add a
@@ -35,7 +35,7 @@ other commands).
 
 Plugins can also register handlers to run on every tick, and can interface with
 the built-in `enable` and `disable` commands. For the full plugin API, see the
-skeleton plugins or ``PluginManager.cpp``.
+example plugins or ``PluginManager.cpp``.
 
 Installed plugins live in the ``hack/plugins`` folder of a DFHack installation,
 and the `load` family of commands can be used to load a recompiled plugin
diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt
index 338db4ab9..6a34117b9 100644
--- a/plugins/CMakeLists.txt
+++ b/plugins/CMakeLists.txt
@@ -185,12 +185,6 @@ if(BUILD_SUPPORTED)
     # see instructions for adding "external" plugins at the end of this file.
 endif()
 
-# this is the skeleton plugin. If you want to make your own, make a copy and then change it
-option(BUILD_SKELETON "Build the skeleton plugin." OFF)
-if(BUILD_SKELETON)
-    add_subdirectory(skeleton)
-endif()
-
 macro(subdirlist result subdir)
     file(GLOB children ABSOLUTE ${subdir}/ ${subdir}/*/)
     set(dirlist "")
diff --git a/plugins/skeleton/skeleton.cpp b/plugins/examples/skeleton.cpp
similarity index 100%
rename from plugins/skeleton/skeleton.cpp
rename to plugins/examples/skeleton.cpp
diff --git a/plugins/skeleton/skeletonShort.cpp b/plugins/examples/skeletonShort.cpp
similarity index 100%
rename from plugins/skeleton/skeletonShort.cpp
rename to plugins/examples/skeletonShort.cpp
diff --git a/plugins/skeleton/CMakeLists.txt b/plugins/skeleton/CMakeLists.txt
deleted file mode 100644
index cbe5f7ce6..000000000
--- a/plugins/skeleton/CMakeLists.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-project(skeleton)
-# A list of source files
-set(PROJECT_SRCS
-    skeleton.cpp
-)
-# A list of headers
-set(PROJECT_HDRS
-    skeleton.h
-)
-set_source_files_properties(${PROJECT_HDRS} PROPERTIES HEADER_FILE_ONLY TRUE)
-
-# mash them together (headers are marked as headers and nothing will try to compile them)
-list(APPEND PROJECT_SRCS ${PROJECT_HDRS})
-
-# option to use a thread for no particular reason
-option(SKELETON_THREAD "Use threads in the skeleton plugin." ON)
-if(UNIX)
-    if(APPLE)
-        set(PROJECT_LIBS
-            # add any extra mac libraries here
-            ${PROJECT_LIBS}
-        )
-    else()
-        set(PROJECT_LIBS
-            # add any extra linux libraries here
-            ${PROJECT_LIBS}
-        )
-    endif()
-else()
-    set(PROJECT_LIBS
-        # add any extra windows libraries here
-        ${PROJECT_LIBS}
-    )
-endif()
-# this makes sure all the stuff is put in proper places and linked to dfhack
-dfhack_plugin(skeleton ${PROJECT_SRCS} LINK_LIBRARIES ${PROJECT_LIBS})
diff --git a/plugins/skeleton/skeleton.h b/plugins/skeleton/skeleton.h
deleted file mode 100644
index 6f70f09be..000000000
--- a/plugins/skeleton/skeleton.h
+++ /dev/null
@@ -1 +0,0 @@
-#pragma once

From 0bbbacf161aa0f4bd4869d108f56d85f9c5ec8e6 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Tue, 2 Aug 2022 18:40:50 -0700
Subject: [PATCH 2/9] extend the docs and examples in skeleton.cpp

---
 plugins/examples/skeleton.cpp | 221 +++++++++++++++++++++-------------
 1 file changed, 134 insertions(+), 87 deletions(-)

diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index 7d5936f6d..e1f552d31 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -1,65 +1,71 @@
-// This is a generic plugin that does nothing useful apart from acting as an example... of a plugin that does nothing :D
+// This is an example plugin that just documents and implements all the plugin
+// callbacks and features. You can compile it, load it, run it, and see the
+// debug messages get printed to the console.
+//
+// See the other example plugins in this directory for plugins that are
+// configured for specific use cases (but don't come with as many comments as
+// this one does).
+
+#include <string>
+#include <vector>
+
+#include "df/world.h"
 
-// some headers required for a plugin. Nothing special, just the basics.
 #include "Core.h"
-#include <Console.h>
-#include <Export.h>
-#include <PluginManager.h>
-#include <modules/EventManager.h>
-// If you need to save data per-world:
-//#include "modules/Persistence.h"
+#include "Debug.h"
+#include "LuaTools.h"
+#include "PluginManager.h"
 
-// DF data structure definition headers
-#include "DataDefs.h"
-//#include "df/world.h"
+#include "modules/Persistence.h"
+#include "modules/World.h"
 
-// our own, empty header.
-#include "skeleton.h"
+using std::string;
+using std::vector;
 
 using namespace DFHack;
-using namespace df::enums;
 
-// Expose the plugin name to the DFHack core, as well as metadata like the DFHack version.
-// The name string provided must correspond to the filename -
+// Expose the plugin name to the DFHack core, as well as metadata like the
+// DFHack version that this plugin was compiled with. This macro provides a
+// variable for the plugin name as const char * plugin_name.
+// The name provided must correspond to the filename --
 // skeleton.plug.so, skeleton.plug.dylib, or skeleton.plug.dll in this case
 DFHACK_PLUGIN("skeleton");
 
-// The identifier declared with this macro (ie. enabled) can be specified by the user
-// and subsequently used to manage the plugin's operations.
-// This will also be tracked by `plug`; when true the plugin will be shown as enabled.
-DFHACK_PLUGIN_IS_ENABLED(enabled);
+// The identifier declared with this macro (i.e. is_enabled) is used to track
+// whether the plugin is in an "enabled" state. If you don't need enablement
+// for your plugin, you don't need this line. This variable will also be read
+// by the `plug` builtin command; when true the plugin will be shown as enabled.
+DFHACK_PLUGIN_IS_ENABLED(is_enabled);
 
 // 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
-// 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);
 
-// You may want some compile time debugging options
-// one easy system just requires you to cache the color_ostream &out into a global debug variable
-//#define P_DEBUG 1
-//uint16_t maxTickFreq = 1200; //maybe you want to use some events
+// logging levels can be dynamically controlled with the `debugfilter` command.
+namespace DFHack {
+    // for configuration-related logging
+    DBG_DECLARE(skeleton, status, DebugCategory::LINFO);
+    // for logging during the periodic scan
+    DBG_DECLARE(skeleton, cycle, DebugCategory::LINFO);
+}
 
-command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters);
+command_result command_callback1(color_ostream &out, vector<string> &parameters);
 
+// run when the plugin is loaded
 DFhackCExport command_result plugin_init(color_ostream &out, std::vector<PluginCommand> &commands) {
-    commands.push_back(PluginCommand("skeleton",
-                                     "~54 character description of plugin", //to use one line in the ``[DFHack]# ls`` output
-                                     command_callback1,
-                                     false,
-                                     "example usage"
-                                     " skeleton <option> <args>\n"
-                                     "    explanation of plugin/command\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"));
+    // For in-tree plugins, don't use the "usage" parameter of PluginCommand.
+    // Instead, add an .rst file with the same name as the plugin to the
+    // docs/plugins/ directory.
+    commands.push_back(PluginCommand(
+        "skeleton",
+        "Short (~54 character) description of command.", // to use one line in the ``[DFHack]# ls`` output
+        command_callback1));
     return CR_OK;
 }
 
+// run when the plugin is unloaded
 DFhackCExport command_result plugin_shutdown(color_ostream &out) {
     // You *MUST* kill all threads you created before this returns.
     // If everything fails, just return CR_FAILURE. Your plugin will be
@@ -68,28 +74,20 @@ DFhackCExport command_result plugin_shutdown(color_ostream &out) {
 
 }
 
+// run when the `enable` or `disable` command is run with this plugin name as
+// an argument
 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;
+    // you have to maintain the state of the is_enabled variable yourself. it
+    // doesn't happen automatically.
+    is_enabled = enable;
     return CR_OK;
 }
 
-
-/* OPTIONAL *
 // Called to notify the plugin about important state changes.
 // Invoked with DF suspended, and always before the matching plugin_onupdate.
 // More event codes may be added in the future.
 DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
-    if (enabled) {
+    if (is_enabled) {
         switch (event) {
             case SC_UNKNOWN:
                 break;
@@ -116,9 +114,8 @@ DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_chan
     return CR_OK;
 }
 
-// Whatever you put here will be done in each game step. Don't abuse it.
-DFhackCExport command_result plugin_onupdate ( color_ostream &out )
-{
+// Whatever you put here will be done in each game frame refresh. Don't abuse it.
+DFhackCExport command_result plugin_onupdate (color_ostream &out) {
     // whetever. You don't need to suspend DF execution here.
     return CR_OK;
 }
@@ -128,44 +125,94 @@ DFhackCExport command_result plugin_onupdate ( color_ostream &out )
 // 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
 // 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.
     return CR_OK;
 }
 
-DFhackCExport command_result plugin_load_data (color_ostream &out)
-{
+DFhackCExport command_result plugin_load_data (color_ostream &out) {
     // Call functions in the Persistence module here.
     return CR_OK;
 }
-* OPTIONAL */
-
-
-// A command! It sits around and looks pretty. And it's nice and friendly.
-command_result command_callback1(color_ostream &out, std::vector<std::string> &parameters) {
-    // It's nice to print a help message you get invalid options
-    // from the user instead of just acting strange.
-    // This can be achieved by adding the extended help string to the
-    // PluginCommand registration as show above, and then returning
-    // CR_WRONG_USAGE from the function. The same string will also
-    // be used by 'help your-command'.
-    if (!parameters.empty()) {
-        return CR_WRONG_USAGE; //or maybe you want it to do something else
+
+// define the structure that will represent the possible commandline options
+struct command_options {
+    // whether to display help
+    bool help = false;
+
+    // whether to run a cycle right now
+    bool now = false;
+
+    // how many ticks to wait between cycles when enabled, -1 means unset
+    int32_t ticks = -1;
+
+    // example params of different types
+    df::coord start;
+    string format;
+    vector<string*> list; // note this must be a vector of pointers, not objects
+
+    static struct_identity _identity;
+};
+static const struct_field_info command_options_fields[] = {
+    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "now",    offsetof(command_options, now),   &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
+    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
+    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::END }
+};
+struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
+
+// load the lua module associated with the plugin and parse the commandline
+// in lua (which has better facilities than C++ for string parsing). You should
+// create a file named after your plugin in the plugins/lua directory. This
+// example expects you to define a global function in that file named
+// "parse_commandline" that takes the options struct defined above along with
+// the commandline parameters. It should parse the parameters and set data in
+// the options structure. See plugins/lua/skeleton.lua for an example.
+static bool get_options(color_ostream &out,
+                        command_options &opts,
+                        const vector<string> &parameters)
+{
+    auto L = Lua::Core::State;
+    Lua::StackUnwinder top(L);
+
+    if (!lua_checkstack(L, parameters.size() + 2) ||
+        !Lua::PushModulePublic(
+            out, L, ("plugins." + string(plugin_name)).c_str(),
+            "parse_commandline")) {
+        out.printerr("Failed to load %s Lua code\n", plugin_name);
+        return false;
     }
-    // Commands are called from threads other than the DF one.
-    // Suspend this thread until DF has time for us.
-    // **If you use CoreSuspender** it'll automatically resume DF when
-    // execution leaves the current scope.
+
+    Lua::Push(L, &opts);
+    for (const string &param : parameters)
+        Lua::Push(L, param);
+
+    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
+        return false;
+
+    return true;
+}
+
+// This is the callback we registered in plugin_init. Note that while plugin
+// callbacks are called with the core suspended, command callbacks are called
+// from a different thread and need to explicity suspend the core if they
+// interact with Lua or DF game state (most commands do at least one of these).
+static command_result command_callback1(color_ostream &out, vector<string> &parameters) {
+    // I'll say it again: always suspend the core in command callbacks unless
+    // all your data is local.
     CoreSuspender suspend;
-    // Actually do something here. Yay.
 
-    // process parameters
-    if (parameters.size() == 1 && parameters[0] == "option1") {
-        // stuff
-    } else {
-        return CR_FAILURE;
-    }
-    // Give control back to DF.
+    // Return CR_WRONG_USAGE to print out your help text. The help text is
+    // sourced from the associated rst file in docs/plugins/. The same help will
+    // also be returned by 'help your-command'.
+    command_options opts;
+    if (!get_options(out, opts, parameters) || opts.help)
+        return CR_WRONG_USAGE;
+
+    // TODO: do something according to the flags set in the options struct
+
     return CR_OK;
 }

From 43dfd27bb4e3f36f4e3e037211ae3e85d2aa6a15 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Tue, 2 Aug 2022 18:41:03 -0700
Subject: [PATCH 3/9] create several use-case-focused plugin examples

---
 .../examples/persistent_per_save_example.cpp  | 232 ++++++++++++++++++
 plugins/examples/simple_command_example.cpp   |  96 ++++++++
 plugins/examples/skeletonShort.cpp            |  61 -----
 plugins/examples/ui_addition_example.cpp      |  58 +++++
 4 files changed, 386 insertions(+), 61 deletions(-)
 create mode 100644 plugins/examples/persistent_per_save_example.cpp
 create mode 100644 plugins/examples/simple_command_example.cpp
 delete mode 100644 plugins/examples/skeletonShort.cpp
 create mode 100644 plugins/examples/ui_addition_example.cpp

diff --git a/plugins/examples/persistent_per_save_example.cpp b/plugins/examples/persistent_per_save_example.cpp
new file mode 100644
index 000000000..b620b7703
--- /dev/null
+++ b/plugins/examples/persistent_per_save_example.cpp
@@ -0,0 +1,232 @@
+// This template is appropriate for plugins that periodically check game state
+// and make some sort of automated change. These types of plugins typically
+// provide a command that can be used to configure the plugin behavior and
+// require a world to be loaded before they can function. This kind of plugin
+// should persist its state in the savegame and auto-re-enable itself when a
+// savegame that had this plugin enabled is loaded.
+
+#include <string>
+#include <vector>
+
+#include "df/world.h"
+
+#include "Core.h"
+#include "Debug.h"
+#include "LuaTools.h"
+#include "PluginManager.h"
+
+#include "modules/Persistence.h"
+#include "modules/World.h"
+
+using std::string;
+using std::vector;
+
+using namespace DFHack;
+
+DFHACK_PLUGIN("persistent_per_save_example");
+DFHACK_PLUGIN_IS_ENABLED(is_enabled);
+
+REQUIRE_GLOBAL(world);
+
+// logging levels can be dynamically controlled with the `debugfilter` command.
+namespace DFHack {
+    // for configuration-related logging
+    DBG_DECLARE(persistent_per_save_example, status, DebugCategory::LINFO);
+    // for logging during the periodic scan
+    DBG_DECLARE(persistent_per_save_example, cycle, DebugCategory::LINFO);
+}
+
+static const string CONFIG_KEY = string(plugin_name) + "/config";
+static PersistentDataItem config;
+enum ConfigValues {
+    CONFIG_IS_ENABLED = 0,
+    CONFIG_CYCLE_TICKS = 1,
+};
+static int get_config_val(int index) {
+    if (!config.isValid())
+        return -1;
+    return config.ival(index);
+}
+static bool get_config_bool(int index) {
+    return get_config_val(index) == 1;
+}
+static void set_config_val(int index, int value) {
+    if (config.isValid())
+        config.ival(index) = value;
+}
+static void set_config_bool(int index, bool value) {
+    set_config_val(index, value ? 1 : 0);
+}
+
+static int32_t cycle_timestamp = 0;  // world->frame_counter at last cycle
+
+// define the structure that will represent the possible commandline options
+struct command_options {
+    // whether to display help
+    bool help = false;
+
+    // whether to run a cycle right now
+    bool now = false;
+
+    // how many ticks to wait between cycles when enabled, -1 means unset
+    int32_t ticks = -1;
+
+    // example params of different types
+    df::coord start;
+    string format;
+    vector<string*> list; // note this must be a vector of pointers, not objects
+
+    static struct_identity _identity;
+};
+static const struct_field_info command_options_fields[] = {
+    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "now",    offsetof(command_options, now),   &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
+    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
+    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::END }
+};
+struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
+
+static command_result do_command(color_ostream &out, vector<string> &parameters);
+static void do_cycle(color_ostream &out);
+
+DFhackCExport command_result plugin_init(color_ostream &out, std::vector <PluginCommand> &commands) {
+    DEBUG(status,out).print("initializing %s\n", plugin_name);
+
+    // provide a configuration interface for the plugin
+    commands.push_back(PluginCommand(
+        plugin_name,
+        "Short (~54 character) description of command.",
+        do_command));
+
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
+    if (!Core::getInstance().isWorldLoaded()) {
+        out.printerr("Cannot enable %s without a loaded world.\n", plugin_name);
+        return CR_FAILURE;
+    }
+
+    if (enable != is_enabled) {
+        is_enabled = enable;
+        DEBUG(status,out).print("%s from the API; persisting\n",
+                                is_enabled ? "enabled" : "disabled");
+        set_config_bool(CONFIG_IS_ENABLED, is_enabled);
+    } else {
+        DEBUG(status,out).print("%s from the API, but already %s; no action\n",
+                                is_enabled ? "enabled" : "disabled",
+                                is_enabled ? "enabled" : "disabled");
+    }
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_shutdown (color_ostream &out) {
+    DEBUG(status,out).print("shutting down %s\n", plugin_name);
+
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_load_data (color_ostream &out) {
+    config = World::GetPersistentData(CONFIG_KEY);
+
+    if (!config.isValid()) {
+        DEBUG(status,out).print("no config found in this save; initializing\n");
+        config = World::AddPersistentData(CONFIG_KEY);
+        set_config_bool(CONFIG_IS_ENABLED, is_enabled);
+        set_config_val(CONFIG_CYCLE_TICKS, 6000);
+    }
+
+    // we have to copy our enabled flag into the global plugin variable, but
+    // all the other state we can directly read/modify from the persistent
+    // data structure.
+    is_enabled = get_config_bool(CONFIG_IS_ENABLED);
+    DEBUG(status,out).print("loading persisted enabled state: %s\n",
+                            is_enabled ? "true" : "false");
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
+    if (event == DFHack::SC_MAP_UNLOADED) {
+        if (is_enabled) {
+            DEBUG(status,out).print("world unloaded; disabling %s\n",
+                                    plugin_name);
+            is_enabled = false;
+        }
+    }
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_onupdate(color_ostream &out) {
+    if (is_enabled && world->frame_counter - cycle_timestamp >= get_config_val(CONFIG_CYCLE_TICKS))
+        do_cycle(out);
+    return CR_OK;
+}
+
+// load the lua module associated with the plugin and parse the commandline
+// in lua (which has better facilities than C++ for string parsing).
+static bool get_options(color_ostream &out,
+                        command_options &opts,
+                        const vector<string> &parameters)
+{
+    auto L = Lua::Core::State;
+    Lua::StackUnwinder top(L);
+
+    if (!lua_checkstack(L, parameters.size() + 2) ||
+        !Lua::PushModulePublic(
+            out, L, ("plugins." + string(plugin_name)).c_str(),
+            "parse_commandline")) {
+        out.printerr("Failed to load %s Lua code\n", plugin_name);
+        return false;
+    }
+
+    Lua::Push(L, &opts);
+    for (const string &param : parameters)
+        Lua::Push(L, param);
+
+    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
+        return false;
+
+    return true;
+}
+
+static command_result do_command(color_ostream &out, vector<string> &parameters) {
+    // be sure to suspend the core if any DF state is read or modified
+    CoreSuspender suspend;
+
+    if (!Core::getInstance().isWorldLoaded()) {
+        out.printerr("Cannot run %s without a loaded world.\n", plugin_name);
+        return CR_FAILURE;
+    }
+
+    command_options opts;
+    if (!get_options(out, opts, parameters) || opts.help)
+        return CR_WRONG_USAGE;
+
+    if (opts.ticks > -1) {
+        set_config_val(CONFIG_CYCLE_TICKS, opts.ticks);
+        INFO(status,out).print("New cycle timer: %d ticks.\n", opts.ticks);
+    }
+    else if (opts.now) {
+        do_cycle(out);
+    }
+    else {
+        out.print("%s is %srunning\n", plugin_name, (is_enabled ? "" : "not "));
+    }
+    return CR_OK;
+}
+
+/////////////////////////////////////////////////////
+// cycle logic
+//
+
+static void do_cycle(color_ostream &out) {
+    // mark that we have recently run
+    cycle_timestamp = world->frame_counter;
+
+    DEBUG(cycle,out).print("running %s cycle\n", plugin_name);
+
+    // TODO: logic that runs every get_config_val(CONFIG_CYCLE_TICKS) ticks
+}
diff --git a/plugins/examples/simple_command_example.cpp b/plugins/examples/simple_command_example.cpp
new file mode 100644
index 000000000..0f1aad4f1
--- /dev/null
+++ b/plugins/examples/simple_command_example.cpp
@@ -0,0 +1,96 @@
+// This template is appropriate for plugins that simply provide one or more
+// commands, but don't need to be "enabled" to function.
+
+#include <string>
+#include <vector>
+
+#include "Debug.h"
+#include "LuaTools.h"
+#include "PluginManager.h"
+
+using std::string;
+using std::vector;
+
+using namespace DFHack;
+
+DFHACK_PLUGIN("simple_command_example");
+
+namespace DFHack {
+    DBG_DECLARE(simple_command_example, log);
+}
+
+// define the structure that will represent the possible commandline options
+struct command_options {
+    // whether to display help
+    bool help = false;
+
+    // example params of different types
+    int32_t ticks = -1;
+    df::coord start;
+    string format;
+    vector<string*> list; // note this must be a vector of pointers, not objects
+
+    static struct_identity _identity;
+};
+static const struct_field_info command_options_fields[] = {
+    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
+    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
+    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
+    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
+    { struct_field_info::END }
+};
+struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
+
+static command_result do_command(color_ostream &out, vector<string> &parameters);
+
+DFhackCExport command_result plugin_init(color_ostream &out, std::vector <PluginCommand> &commands) {
+    DEBUG(log,out).print("initializing %s\n", plugin_name);
+
+    commands.push_back(PluginCommand(
+        plugin_name,
+        "Short (~54 character) description of command.",
+        do_command));
+
+    return CR_OK;
+}
+
+// load the lua module associated with the plugin and parse the commandline
+// in lua (which has better facilities than C++ for string parsing).
+static bool get_options(color_ostream &out,
+                        command_options &opts,
+                        const vector<string> &parameters)
+{
+    auto L = Lua::Core::State;
+    Lua::StackUnwinder top(L);
+
+    if (!lua_checkstack(L, parameters.size() + 2) ||
+        !Lua::PushModulePublic(
+            out, L, ("plugins." + string(plugin_name)).c_str(),
+            "parse_commandline")) {
+        out.printerr("Failed to load %s Lua code\n", plugin_name);
+        return false;
+    }
+
+    Lua::Push(L, &opts);
+    for (const string &param : parameters)
+        Lua::Push(L, param);
+
+    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
+        return false;
+
+    return true;
+}
+
+static command_result do_command(color_ostream &out, vector<string> &parameters) {
+    // be sure to suspend the core if any DF state is read or modified
+    CoreSuspender suspend;
+
+    command_options opts;
+    if (!get_options(out, opts, parameters) || opts.help)
+        return CR_WRONG_USAGE;
+
+    // TODO: command logic
+
+    return CR_OK;
+}
diff --git a/plugins/examples/skeletonShort.cpp b/plugins/examples/skeletonShort.cpp
deleted file mode 100644
index 93712c5a5..000000000
--- a/plugins/examples/skeletonShort.cpp
+++ /dev/null
@@ -1,61 +0,0 @@
-#include "Core.h"
-#include <Console.h>
-#include <Export.h>
-#include <PluginManager.h>
-#include <modules/EventManager.h>
-
-//#include "df/world.h"
-
-using namespace DFHack;
-using namespace df::enums;
-
-DFHACK_PLUGIN("skeleton2");
-DFHACK_PLUGIN_IS_ENABLED(enabled);
-//REQUIRE_GLOBAL(world);
-
-command_result skeleton2 (color_ostream &out, std::vector <std::string> & parameters);
-
-DFhackCExport command_result plugin_init (color_ostream &out, std::vector <PluginCommand> &commands) {
-    commands.push_back(PluginCommand("skeleton2",
-                                     "~54 character description of plugin", //to use one line in the ``[DFHack]# ls`` output
-                                     skeleton2,
-                                     false,
-                                     "example usage"
-                                     " skeleton2 <option> <args>\n"
-                                     "    explanation of plugin/command\n"
-                                     "\n"
-                                     " skeleton2\n"
-                                     "    what happens when using the command\n"
-                                     "\n"
-                                     " skeleton2 option1\n"
-                                     "    what happens when using the command with option1\n"
-                                     "\n"));
-    return CR_OK;
-}
-
-DFhackCExport command_result plugin_shutdown (color_ostream &out) {
-    return CR_OK;
-}
-
-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;
-    return CR_OK;
-}
-
-command_result skeleton2 (color_ostream &out, std::vector <std::string> & parameters) {
-    if (!parameters.empty())
-        return CR_WRONG_USAGE;
-    CoreSuspender suspend;
-    out.print("blah");
-    return CR_OK;
-}
diff --git a/plugins/examples/ui_addition_example.cpp b/plugins/examples/ui_addition_example.cpp
new file mode 100644
index 000000000..43350a159
--- /dev/null
+++ b/plugins/examples/ui_addition_example.cpp
@@ -0,0 +1,58 @@
+// This template is appropriate for plugins that can be enabled to make some
+// specific persistent change to the game, but don't need a world to be loaded
+// before they are enabled. These types of plugins typically register some sort
+// of hook on enable and clear the hook on disable. They are generally enabled
+// from dfhack.init and do not need to persist and reload their enabled state.
+
+#include <string>
+#include <vector>
+
+#include "df/viewscreen_titlest.h"
+
+#include "Debug.h"
+#include "LuaTools.h"
+#include "PluginManager.h"
+#include "VTableInterpose.h"
+
+using std::string;
+using std::vector;
+
+using namespace DFHack;
+
+DFHACK_PLUGIN("ui_addition_example");
+DFHACK_PLUGIN_IS_ENABLED(is_enabled);
+
+namespace DFHack {
+    DBG_DECLARE(ui_addition_example, log);
+}
+
+// example of hooking a screen so the plugin code will run whenever the screen
+// is visible
+struct title_version_hook : df::viewscreen_titlest {
+    typedef df::viewscreen_titlest interpose_base;
+
+    DEFINE_VMETHOD_INTERPOSE(void, render, ()) {
+        INTERPOSE_NEXT(render)();
+
+        // TODO: injected render logic here
+    }
+};
+IMPLEMENT_VMETHOD_INTERPOSE(title_version_hook, render);
+
+DFhackCExport command_result plugin_shutdown (color_ostream &out) {
+    DEBUG(log,out).print("shutting down %s\n", plugin_name);
+    INTERPOSE_HOOK(title_version_hook, render).remove();
+    return CR_OK;
+}
+
+DFhackCExport command_result plugin_enable (color_ostream &out, bool enable) {
+    if (enable != is_enabled) {
+        DEBUG(log,out).print("%s %s\n", plugin_name,
+                             is_enabled ? "enabled" : "disabled");
+        if (!INTERPOSE_HOOK(title_version_hook, render).apply(enable))
+            return CR_FAILURE;
+
+        is_enabled = enable;
+    }
+    return CR_OK;
+}

From a4c853597754efacb9eb9f430f906035067b052f Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 00:01:25 -0700
Subject: [PATCH 4/9] add argparse int checking methods, more docs

---
 docs/Lua API.rst              | 12 +++++++++
 library/lua/argparse.lua      | 15 +++++++++---
 plugins/CMakeLists.txt        |  6 +++++
 plugins/examples/skeleton.cpp | 41 +++++++++++++++++++++++++------
 plugins/lua/skeleton.lua      | 46 +++++++++++++++++++++++++++++++++++
 test/library/argparse.lua     | 30 +++++++++++++++++++++++
 6 files changed, 139 insertions(+), 11 deletions(-)
 create mode 100644 plugins/lua/skeleton.lua

diff --git a/docs/Lua API.rst b/docs/Lua API.rst
index 55a217757..d1dbc2856 100644
--- a/docs/Lua API.rst	
+++ b/docs/Lua API.rst	
@@ -3029,6 +3029,18 @@ parameters.
   function also verifies that the coordinates are valid for the current map and
   throws if they are not (unless ``skip_validation`` is set to true).
 
+* ``argparse.positiveInt(arg, arg_name)``
+
+  Throws if ``tonumber(arg)`` is not a positive integer; otherwise returns
+  ``tonumber(arg)``. If ``arg_name`` is specified, it is used to make error
+  messages more useful.
+
+* ``argparse.nonnegativeInt(arg, arg_name)``
+
+  Throws if ``tonumber(arg)`` is not a non-negative integer; otherwise returns
+  ``tonumber(arg)``. If ``arg_name`` is specified, it is used to make error
+  messages more useful.
+
 dumper
 ======
 
diff --git a/library/lua/argparse.lua b/library/lua/argparse.lua
index ee170c190..a143f454c 100644
--- a/library/lua/argparse.lua
+++ b/library/lua/argparse.lua
@@ -154,11 +154,20 @@ function numberList(arg, arg_name, list_length)
     return strings
 end
 
--- throws if val is not a nonnegative integer; otherwise returns val
-local function check_nonnegative_int(val, arg_name)
+function positiveInt(arg, arg_name)
+    local val = tonumber(arg)
+    if not val or val <= 0 or val ~= math.floor(val) then
+        arg_error(arg_name,
+                  'expected positive integer; got "%s"', tostring(arg))
+    end
+    return val
+end
+
+function nonnegativeInt(arg, arg_name)
+    local val = tonumber(arg)
     if not val or val < 0 or val ~= math.floor(val) then
         arg_error(arg_name,
-                  'expected non-negative integer; got "%s"', tostring(val))
+                  'expected non-negative integer; got "%s"', tostring(arg))
     end
     return val
 end
diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt
index 6a34117b9..1e2019091 100644
--- a/plugins/CMakeLists.txt
+++ b/plugins/CMakeLists.txt
@@ -185,6 +185,12 @@ if(BUILD_SUPPORTED)
     # see instructions for adding "external" plugins at the end of this file.
 endif()
 
+# this is the skeleton plugin. If you want to make your own, make a copy and then change it
+option(BUILD_SKELETON "Build the skeleton plugin." OFF)
+if(BUILD_SKELETON)
+    dfhack_plugin(skeleton examples/skeleton.cpp LINK_LIBRARIES lua)
+endif()
+
 macro(subdirlist result subdir)
     file(GLOB children ABSOLUTE ${subdir}/ ${subdir}/*/)
     set(dirlist "")
diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index e1f552d31..27621af4a 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -1,6 +1,8 @@
-// This is an example plugin that just documents and implements all the plugin
-// callbacks and features. You can compile it, load it, run it, and see the
-// debug messages get printed to the console.
+// This is an example plugin that documents and implements all the plugin
+// callbacks and features. You can include it in the regular build by setting
+// the BUILD_SKELETON option in CMake to ON. Play with loading and unloading
+// the plugin in various game states (e.g. with and without a world loaded),
+// and see the debug messages get printed to the console.
 //
 // See the other example plugins in this directory for plugins that are
 // configured for specific use cases (but don't come with as many comments as
@@ -44,17 +46,23 @@ DFHACK_PLUGIN_IS_ENABLED(is_enabled);
 REQUIRE_GLOBAL(world);
 
 // logging levels can be dynamically controlled with the `debugfilter` command.
+// Actual plugins will likely want to set the default level to LINFO or LWARNING
+// instead of the LDEBUG used here.
 namespace DFHack {
     // for configuration-related logging
-    DBG_DECLARE(skeleton, status, DebugCategory::LINFO);
-    // for logging during the periodic scan
-    DBG_DECLARE(skeleton, cycle, DebugCategory::LINFO);
+    DBG_DECLARE(skeleton, status, DebugCategory::LDEBUG);
+    // run `debugfilter set debug skeleton onupdate` to see logging in plugin_onupdate
+    DBG_DECLARE(skeleton, onupdate, DebugCategory::LINFO);
+    // for command-related logging
+    DBG_DECLARE(skeleton, command, DebugCategory::LDEBUG);
 }
 
-command_result command_callback1(color_ostream &out, vector<string> &parameters);
+static command_result command_callback1(color_ostream &out, vector<string> &parameters);
 
 // run when the plugin is loaded
 DFhackCExport command_result plugin_init(color_ostream &out, std::vector<PluginCommand> &commands) {
+    DEBUG(status,out).print("initializing %s\n", plugin_name);
+
     // For in-tree plugins, don't use the "usage" parameter of PluginCommand.
     // Instead, add an .rst file with the same name as the plugin to the
     // docs/plugins/ directory.
@@ -67,6 +75,8 @@ DFhackCExport command_result plugin_init(color_ostream &out, std::vector<PluginC
 
 // run when the plugin is unloaded
 DFhackCExport command_result plugin_shutdown(color_ostream &out) {
+    DEBUG(status,out).print("shutting down %s\n", plugin_name);
+
     // You *MUST* kill all threads you created before this returns.
     // If everything fails, just return CR_FAILURE. Your plugin will be
     // in a zombie state, but things won't crash.
@@ -77,6 +87,8 @@ DFhackCExport command_result plugin_shutdown(color_ostream &out) {
 // run when the `enable` or `disable` command is run with this plugin name as
 // an argument
 DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
+    DEBUG(status,out).print("%s from the API\n", enable ? "enabled" : "disabled");
+
     // you have to maintain the state of the is_enabled variable yourself. it
     // doesn't happen automatically.
     is_enabled = enable;
@@ -87,6 +99,8 @@ DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
 // Invoked with DF suspended, and always before the matching plugin_onupdate.
 // More event codes may be added in the future.
 DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
+    DEBUG(status,out).print("game state changed: %d\n", event);
+
     if (is_enabled) {
         switch (event) {
             case SC_UNKNOWN:
@@ -111,12 +125,16 @@ DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_chan
                 break;
         }
     }
+
     return CR_OK;
 }
 
 // Whatever you put here will be done in each game frame refresh. Don't abuse it.
+// Note that if the plugin implements the enabled API, this function is only called
+// if the plugin is enabled.
 DFhackCExport command_result plugin_onupdate (color_ostream &out) {
-    // whetever. You don't need to suspend DF execution here.
+    DEBUG(onupdate,out).print("onupdate called\n");
+
     return CR_OK;
 }
 
@@ -126,11 +144,15 @@ DFhackCExport command_result plugin_onupdate (color_ostream &out) {
 // is loaded or unloaded while a world is active, plugin_save_data or
 // plugin_load_data will be called immediately.
 DFhackCExport command_result plugin_save_data (color_ostream &out) {
+    DEBUG(status,out).print("save or unload is imminent; time to persist state\n");
+
     // Call functions in the Persistence module here.
     return CR_OK;
 }
 
 DFhackCExport command_result plugin_load_data (color_ostream &out) {
+    DEBUG(status,out).print("world is loading; time to load persisted state\n");
+
     // Call functions in the Persistence module here.
     return CR_OK;
 }
@@ -201,6 +223,9 @@ static bool get_options(color_ostream &out,
 // from a different thread and need to explicity suspend the core if they
 // interact with Lua or DF game state (most commands do at least one of these).
 static command_result command_callback1(color_ostream &out, vector<string> &parameters) {
+    DEBUG(command,out).print("%s command called with %zu parameters\n",
+        plugin_name, parameters.size());
+
     // I'll say it again: always suspend the core in command callbacks unless
     // all your data is local.
     CoreSuspender suspend;
diff --git a/plugins/lua/skeleton.lua b/plugins/lua/skeleton.lua
new file mode 100644
index 000000000..60af229cc
--- /dev/null
+++ b/plugins/lua/skeleton.lua
@@ -0,0 +1,46 @@
+local _ENV = mkmodule('plugins.skeleton')
+
+local argparse = require('argparse')
+local utils = require('utils')
+
+local VALID_FORMATS = utils.invert{'pretty', 'normal', 'ugly'}
+
+local function do_commandline(opts, args)
+    print(('called with %d arguments:'):format(#args))
+    for _,arg in ipairs(args) do
+        print('  ' .. arg)
+    end
+
+    local positionals = argparse.processArgsGetopt(args, {
+            {'t', 'ticks', hasArg=true,
+             handler=function(arg) opts.ticks =
+                    argparse.check_positive_int(arg, 'ticks') end},
+            {'s', 'start', hasArg=true,
+             handler=function(arg) utils.assign(
+                    opts.start, argpars.coors(arg, 'start')) end},
+            {'h', 'help', handler=function() opts.help = true end},
+            {'f', 'format', hasArg=true,
+             handler=function(arg) opts.format = arg end},
+            {'z', 'cur-zlevel', handler=function() use_zlevel = true end},
+        })
+
+    if positionals[1] == 'help' then opts.help = true end
+    if opts.help then return end
+
+    if positionals[1] == 'now' then
+        opts.now = true
+    end
+
+    if #opts.format > 0 and not VALID_FORMATS[opts.format] then
+        qerror(('invalid format name: "%s"'):format(opts.format))
+    end
+end
+
+function parse_commandline(opts, ...)
+    do_commandline(opts, {...})
+
+    print('populated options data structure:')
+    printall_recurse(opts)
+end
+
+return _ENV
diff --git a/test/library/argparse.lua b/test/library/argparse.lua
index 4e5c48acc..5e85e6465 100644
--- a/test/library/argparse.lua
+++ b/test/library/argparse.lua
@@ -265,3 +265,33 @@ function test.coords()
                 end)
         end)
 end
+
+function test.positiveInt()
+    expect.eq(5, argparse.positiveInt(5))
+    expect.eq(5, argparse.positiveInt('5'))
+    expect.eq(5, argparse.positiveInt('5.0'))
+    expect.eq(1, argparse.positiveInt('1'))
+
+    expect.error_match('expected positive integer',
+                       function() argparse.positiveInt('0') end)
+    expect.error_match('expected positive integer',
+                       function() argparse.positiveInt('5.01') end)
+    expect.error_match('expected positive integer',
+                       function() argparse.positiveInt(-1) end)
+end
+
+function test.nonnegativeInt()
+    expect.eq(5, argparse.nonnegativeInt(5))
+    expect.eq(5, argparse.nonnegativeInt('5'))
+    expect.eq(5, argparse.nonnegativeInt('5.0'))
+    expect.eq(1, argparse.nonnegativeInt('1'))
+    expect.eq(0, argparse.nonnegativeInt('0'))
+    expect.eq(0, argparse.nonnegativeInt('-0'))
+
+    expect.error_match('expected non%-negative integer',
+                       function() argparse.nonnegativeInt('-0.01') end)
+    expect.error_match('expected non%-negative integer',
+                       function() argparse.nonnegativeInt(-5) end)
+    expect.error_match('expected non%-negative integer',
+                       function() argparse.nonnegativeInt(-1) end)
+end

From a28cf6d444a49fac361fabf6a58cb85c707b366c Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 00:11:18 -0700
Subject: [PATCH 5/9] remove all lua integration from the examples

---
 plugins/CMakeLists.txt                        |  2 +-
 .../examples/persistent_per_save_example.cpp  | 74 +------------------
 plugins/examples/simple_command_example.cpp   | 55 --------------
 plugins/examples/skeleton.cpp                 | 69 +----------------
 plugins/examples/ui_addition_example.cpp      |  1 -
 plugins/lua/skeleton.lua                      | 46 ------------
 6 files changed, 9 insertions(+), 238 deletions(-)
 delete mode 100644 plugins/lua/skeleton.lua

diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt
index 1e2019091..969d3774a 100644
--- a/plugins/CMakeLists.txt
+++ b/plugins/CMakeLists.txt
@@ -188,7 +188,7 @@ endif()
 # this is the skeleton plugin. If you want to make your own, make a copy and then change it
 option(BUILD_SKELETON "Build the skeleton plugin." OFF)
 if(BUILD_SKELETON)
-    dfhack_plugin(skeleton examples/skeleton.cpp LINK_LIBRARIES lua)
+    dfhack_plugin(skeleton examples/skeleton.cpp)
 endif()
 
 macro(subdirlist result subdir)
diff --git a/plugins/examples/persistent_per_save_example.cpp b/plugins/examples/persistent_per_save_example.cpp
index b620b7703..be2f1730c 100644
--- a/plugins/examples/persistent_per_save_example.cpp
+++ b/plugins/examples/persistent_per_save_example.cpp
@@ -12,7 +12,6 @@
 
 #include "Core.h"
 #include "Debug.h"
-#include "LuaTools.h"
 #include "PluginManager.h"
 
 #include "modules/Persistence.h"
@@ -60,35 +59,6 @@ static void set_config_bool(int index, bool value) {
 
 static int32_t cycle_timestamp = 0;  // world->frame_counter at last cycle
 
-// define the structure that will represent the possible commandline options
-struct command_options {
-    // whether to display help
-    bool help = false;
-
-    // whether to run a cycle right now
-    bool now = false;
-
-    // how many ticks to wait between cycles when enabled, -1 means unset
-    int32_t ticks = -1;
-
-    // example params of different types
-    df::coord start;
-    string format;
-    vector<string*> list; // note this must be a vector of pointers, not objects
-
-    static struct_identity _identity;
-};
-static const struct_field_info command_options_fields[] = {
-    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
-    { struct_field_info::PRIMITIVE,      "now",    offsetof(command_options, now),   &df::identity_traits<bool>::identity,    0, 0 },
-    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
-    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
-    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::END }
-};
-struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
-
 static command_result do_command(color_ostream &out, vector<string> &parameters);
 static void do_cycle(color_ostream &out);
 
@@ -165,33 +135,6 @@ DFhackCExport command_result plugin_onupdate(color_ostream &out) {
     return CR_OK;
 }
 
-// load the lua module associated with the plugin and parse the commandline
-// in lua (which has better facilities than C++ for string parsing).
-static bool get_options(color_ostream &out,
-                        command_options &opts,
-                        const vector<string> &parameters)
-{
-    auto L = Lua::Core::State;
-    Lua::StackUnwinder top(L);
-
-    if (!lua_checkstack(L, parameters.size() + 2) ||
-        !Lua::PushModulePublic(
-            out, L, ("plugins." + string(plugin_name)).c_str(),
-            "parse_commandline")) {
-        out.printerr("Failed to load %s Lua code\n", plugin_name);
-        return false;
-    }
-
-    Lua::Push(L, &opts);
-    for (const string &param : parameters)
-        Lua::Push(L, param);
-
-    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
-        return false;
-
-    return true;
-}
-
 static command_result do_command(color_ostream &out, vector<string> &parameters) {
     // be sure to suspend the core if any DF state is read or modified
     CoreSuspender suspend;
@@ -201,20 +144,11 @@ static command_result do_command(color_ostream &out, vector<string> &parameters)
         return CR_FAILURE;
     }
 
-    command_options opts;
-    if (!get_options(out, opts, parameters) || opts.help)
-        return CR_WRONG_USAGE;
+    // TODO: configuration logic
+    // simple commandline parsing can be done in C++, but there are lua libraries
+    // that can easily handle more complex commandlines. see the blueprint plugin
+    // for an example.
 
-    if (opts.ticks > -1) {
-        set_config_val(CONFIG_CYCLE_TICKS, opts.ticks);
-        INFO(status,out).print("New cycle timer: %d ticks.\n", opts.ticks);
-    }
-    else if (opts.now) {
-        do_cycle(out);
-    }
-    else {
-        out.print("%s is %srunning\n", plugin_name, (is_enabled ? "" : "not "));
-    }
     return CR_OK;
 }
 
diff --git a/plugins/examples/simple_command_example.cpp b/plugins/examples/simple_command_example.cpp
index 0f1aad4f1..7b12a1271 100644
--- a/plugins/examples/simple_command_example.cpp
+++ b/plugins/examples/simple_command_example.cpp
@@ -5,7 +5,6 @@
 #include <vector>
 
 #include "Debug.h"
-#include "LuaTools.h"
 #include "PluginManager.h"
 
 using std::string;
@@ -19,29 +18,6 @@ namespace DFHack {
     DBG_DECLARE(simple_command_example, log);
 }
 
-// define the structure that will represent the possible commandline options
-struct command_options {
-    // whether to display help
-    bool help = false;
-
-    // example params of different types
-    int32_t ticks = -1;
-    df::coord start;
-    string format;
-    vector<string*> list; // note this must be a vector of pointers, not objects
-
-    static struct_identity _identity;
-};
-static const struct_field_info command_options_fields[] = {
-    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
-    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
-    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
-    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::END }
-};
-struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
-
 static command_result do_command(color_ostream &out, vector<string> &parameters);
 
 DFhackCExport command_result plugin_init(color_ostream &out, std::vector <PluginCommand> &commands) {
@@ -55,41 +31,10 @@ DFhackCExport command_result plugin_init(color_ostream &out, std::vector <Plugin
     return CR_OK;
 }
 
-// load the lua module associated with the plugin and parse the commandline
-// in lua (which has better facilities than C++ for string parsing).
-static bool get_options(color_ostream &out,
-                        command_options &opts,
-                        const vector<string> &parameters)
-{
-    auto L = Lua::Core::State;
-    Lua::StackUnwinder top(L);
-
-    if (!lua_checkstack(L, parameters.size() + 2) ||
-        !Lua::PushModulePublic(
-            out, L, ("plugins." + string(plugin_name)).c_str(),
-            "parse_commandline")) {
-        out.printerr("Failed to load %s Lua code\n", plugin_name);
-        return false;
-    }
-
-    Lua::Push(L, &opts);
-    for (const string &param : parameters)
-        Lua::Push(L, param);
-
-    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
-        return false;
-
-    return true;
-}
-
 static command_result do_command(color_ostream &out, vector<string> &parameters) {
     // be sure to suspend the core if any DF state is read or modified
     CoreSuspender suspend;
 
-    command_options opts;
-    if (!get_options(out, opts, parameters) || opts.help)
-        return CR_WRONG_USAGE;
-
     // TODO: command logic
 
     return CR_OK;
diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index 27621af4a..434a7e7b5 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -15,7 +15,6 @@
 
 #include "Core.h"
 #include "Debug.h"
-#include "LuaTools.h"
 #include "PluginManager.h"
 
 #include "modules/Persistence.h"
@@ -157,67 +156,6 @@ DFhackCExport command_result plugin_load_data (color_ostream &out) {
     return CR_OK;
 }
 
-// define the structure that will represent the possible commandline options
-struct command_options {
-    // whether to display help
-    bool help = false;
-
-    // whether to run a cycle right now
-    bool now = false;
-
-    // how many ticks to wait between cycles when enabled, -1 means unset
-    int32_t ticks = -1;
-
-    // example params of different types
-    df::coord start;
-    string format;
-    vector<string*> list; // note this must be a vector of pointers, not objects
-
-    static struct_identity _identity;
-};
-static const struct_field_info command_options_fields[] = {
-    { struct_field_info::PRIMITIVE,      "help",   offsetof(command_options, help),  &df::identity_traits<bool>::identity,    0, 0 },
-    { struct_field_info::PRIMITIVE,      "now",    offsetof(command_options, now),   &df::identity_traits<bool>::identity,    0, 0 },
-    { struct_field_info::PRIMITIVE,      "ticks",  offsetof(command_options, ticks), &df::identity_traits<int32_t>::identity, 0, 0 },
-    { struct_field_info::SUBSTRUCT,      "start",  offsetof(command_options, start), &df::coord::_identity,                   0, 0 },
-    { struct_field_info::PRIMITIVE,      "format", offsetof(command_options, format), df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::STL_VECTOR_PTR, "list",   offsetof(command_options, list),   df::identity_traits<string>::get(),     0, 0 },
-    { struct_field_info::END }
-};
-struct_identity command_options::_identity(sizeof(command_options), &df::allocator_fn<command_options>, NULL, "command_options", NULL, command_options_fields);
-
-// load the lua module associated with the plugin and parse the commandline
-// in lua (which has better facilities than C++ for string parsing). You should
-// create a file named after your plugin in the plugins/lua directory. This
-// example expects you to define a global function in that file named
-// "parse_commandline" that takes the options struct defined above along with
-// the commandline parameters. It should parse the parameters and set data in
-// the options structure. See plugins/lua/skeleton.lua for an example.
-static bool get_options(color_ostream &out,
-                        command_options &opts,
-                        const vector<string> &parameters)
-{
-    auto L = Lua::Core::State;
-    Lua::StackUnwinder top(L);
-
-    if (!lua_checkstack(L, parameters.size() + 2) ||
-        !Lua::PushModulePublic(
-            out, L, ("plugins." + string(plugin_name)).c_str(),
-            "parse_commandline")) {
-        out.printerr("Failed to load %s Lua code\n", plugin_name);
-        return false;
-    }
-
-    Lua::Push(L, &opts);
-    for (const string &param : parameters)
-        Lua::Push(L, param);
-
-    if (!Lua::SafeCall(out, L, parameters.size() + 1, 0))
-        return false;
-
-    return true;
-}
-
 // This is the callback we registered in plugin_init. Note that while plugin
 // callbacks are called with the core suspended, command callbacks are called
 // from a different thread and need to explicity suspend the core if they
@@ -233,9 +171,10 @@ static command_result command_callback1(color_ostream &out, vector<string> &para
     // Return CR_WRONG_USAGE to print out your help text. The help text is
     // sourced from the associated rst file in docs/plugins/. The same help will
     // also be returned by 'help your-command'.
-    command_options opts;
-    if (!get_options(out, opts, parameters) || opts.help)
-        return CR_WRONG_USAGE;
+
+    // simple commandline parsing can be done in C++, but there are lua libraries
+    // that can easily handle more complex commandlines. see the blueprint plugin
+    // for an example.
 
     // TODO: do something according to the flags set in the options struct
 
diff --git a/plugins/examples/ui_addition_example.cpp b/plugins/examples/ui_addition_example.cpp
index 43350a159..bbd3af3de 100644
--- a/plugins/examples/ui_addition_example.cpp
+++ b/plugins/examples/ui_addition_example.cpp
@@ -10,7 +10,6 @@
 #include "df/viewscreen_titlest.h"
 
 #include "Debug.h"
-#include "LuaTools.h"
 #include "PluginManager.h"
 #include "VTableInterpose.h"
 
diff --git a/plugins/lua/skeleton.lua b/plugins/lua/skeleton.lua
deleted file mode 100644
index 60af229cc..000000000
--- a/plugins/lua/skeleton.lua
+++ /dev/null
@@ -1,46 +0,0 @@
-local _ENV = mkmodule('plugins.skeleton')
-
-local argparse = require('argparse')
-local utils = require('utils')
-
-local VALID_FORMATS = utils.invert{'pretty', 'normal', 'ugly'}
-
-local function do_commandline(opts, args)
-    print(('called with %d arguments:'):format(#args))
-    for _,arg in ipairs(args) do
-        print('  ' .. arg)
-    end
-
-    local positionals = argparse.processArgsGetopt(args, {
-            {'t', 'ticks', hasArg=true,
-             handler=function(arg) opts.ticks =
-                    argparse.check_positive_int(arg, 'ticks') end},
-            {'s', 'start', hasArg=true,
-             handler=function(arg) utils.assign(
-                    opts.start, argpars.coors(arg, 'start')) end},
-            {'h', 'help', handler=function() opts.help = true end},
-            {'f', 'format', hasArg=true,
-             handler=function(arg) opts.format = arg end},
-            {'z', 'cur-zlevel', handler=function() use_zlevel = true end},
-        })
-
-    if positionals[1] == 'help' then opts.help = true end
-    if opts.help then return end
-
-    if positionals[1] == 'now' then
-        opts.now = true
-    end
-
-    if #opts.format > 0 and not VALID_FORMATS[opts.format] then
-        qerror(('invalid format name: "%s"'):format(opts.format))
-    end
-end
-
-function parse_commandline(opts, ...)
-    do_commandline(opts, {...})
-
-    print('populated options data structure:')
-    printall_recurse(opts)
-end
-
-return _ENV

From 23ced99131c24616591794d334bdc252c5b6cd3c Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 00:30:46 -0700
Subject: [PATCH 6/9] fix call to new functions in existing coord fn

---
 library/lua/argparse.lua | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/library/lua/argparse.lua b/library/lua/argparse.lua
index a143f454c..e094bbb57 100644
--- a/library/lua/argparse.lua
+++ b/library/lua/argparse.lua
@@ -186,9 +186,9 @@ function coords(arg, arg_name, skip_validation)
         return cursor
     end
     local numbers = numberList(arg, arg_name, 3)
-    local pos = xyz2pos(check_nonnegative_int(numbers[1]),
-                        check_nonnegative_int(numbers[2]),
-                        check_nonnegative_int(numbers[3]))
+    local pos = xyz2pos(nonnegativeInt(numbers[1]),
+                        nonnegativeInt(numbers[2]),
+                        nonnegativeInt(numbers[3]))
     if not skip_validation and not dfhack.maps.isValidTilePos(pos) then
         arg_error(arg_name,
                   'specified coordinates not on current map: "%s"', arg)

From 06f1f533acd93c349c059cae3376a9df5d80c93c Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 00:33:24 -0700
Subject: [PATCH 7/9] build the skeleton in the "all plugins" build

---
 .github/workflows/build.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index bef01888f..e922ecaca 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -86,6 +86,7 @@ jobs:
           -DBUILD_TESTS:BOOL=ON \
           -DBUILD_DEV_PLUGINS:BOOL=${{ matrix.plugins == 'all' }} \
           -DBUILD_SIZECHECK:BOOL=${{ matrix.plugins == 'all' }} \
+          -DBUILD_SKELETON:BOOL=${{ matrix.plugins == 'all' }} \
           -DBUILD_STONESENSE:BOOL=${{ matrix.plugins == 'all' }} \
           -DBUILD_SUPPORTED:BOOL=1 \
           -DCMAKE_C_COMPILER_LAUNCHER=ccache \

From f400ee50f87b8a4041fec0adc39db4d96afd688d Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 16:18:22 -0700
Subject: [PATCH 8/9] refine docs, logging, help text

---
 docs/Dev-intro.rst                            |  2 +-
 .../examples/persistent_per_save_example.cpp  |  2 +-
 plugins/examples/skeleton.cpp                 | 63 +++++++++++--------
 3 files changed, 38 insertions(+), 29 deletions(-)

diff --git a/docs/Dev-intro.rst b/docs/Dev-intro.rst
index d4167aae3..c87154594 100644
--- a/docs/Dev-intro.rst
+++ b/docs/Dev-intro.rst
@@ -35,7 +35,7 @@ other commands).
 
 Plugins can also register handlers to run on every tick, and can interface with
 the built-in `enable` and `disable` commands. For the full plugin API, see the
-example plugins or ``PluginManager.cpp``.
+example ``skeleton`` plugin or ``PluginManager.cpp``.
 
 Installed plugins live in the ``hack/plugins`` folder of a DFHack installation,
 and the `load` family of commands can be used to load a recompiled plugin
diff --git a/plugins/examples/persistent_per_save_example.cpp b/plugins/examples/persistent_per_save_example.cpp
index be2f1730c..5a7bf5224 100644
--- a/plugins/examples/persistent_per_save_example.cpp
+++ b/plugins/examples/persistent_per_save_example.cpp
@@ -119,7 +119,7 @@ DFhackCExport command_result plugin_load_data (color_ostream &out) {
 }
 
 DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
-    if (event == DFHack::SC_MAP_UNLOADED) {
+    if (event == DFHack::SC_WORLD_UNLOADED) {
         if (is_enabled) {
             DEBUG(status,out).print("world unloaded; disabling %s\n",
                                     plugin_name);
diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index 434a7e7b5..e8553bdd6 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -98,31 +98,37 @@ DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) {
 // Invoked with DF suspended, and always before the matching plugin_onupdate.
 // More event codes may be added in the future.
 DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {
-    DEBUG(status,out).print("game state changed: %d\n", event);
-
-    if (is_enabled) {
-        switch (event) {
-            case SC_UNKNOWN:
-                break;
-            case SC_WORLD_LOADED:
-                break;
-            case SC_WORLD_UNLOADED:
-                break;
-            case SC_MAP_LOADED:
-                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;
-        }
+    switch (event) {
+        case SC_UNKNOWN:
+            DEBUG(status,out).print("game state changed: SC_UNKNOWN\n");
+            break;
+        case SC_WORLD_LOADED:
+            DEBUG(status,out).print("game state changed: SC_WORLD_LOADED\n");
+            break;
+        case SC_WORLD_UNLOADED:
+            DEBUG(status,out).print("game state changed: SC_WORLD_UNLOADED\n");
+            break;
+        case SC_MAP_LOADED:
+            DEBUG(status,out).print("game state changed: SC_MAP_LOADED\n");
+            break;
+        case SC_MAP_UNLOADED:
+            DEBUG(status,out).print("game state changed: SC_MAP_UNLOADED\n");
+            break;
+        case SC_VIEWSCREEN_CHANGED:
+            DEBUG(status,out).print("game state changed: SC_VIEWSCREEN_CHANGED\n");
+            break;
+        case SC_CORE_INITIALIZED:
+            DEBUG(status,out).print("game state changed: SC_CORE_INITIALIZED\n");
+            break;
+        case SC_BEGIN_UNLOAD:
+            DEBUG(status,out).print("game state changed: SC_BEGIN_UNLOAD\n");
+            break;
+        case SC_PAUSED:
+            DEBUG(status,out).print("game state changed: SC_PAUSED\n");
+            break;
+        case SC_UNPAUSED:
+            DEBUG(status,out).print("game state changed: SC_UNPAUSED\n");
+            break;
     }
 
     return CR_OK;
@@ -145,14 +151,17 @@ DFhackCExport command_result plugin_onupdate (color_ostream &out) {
 DFhackCExport command_result plugin_save_data (color_ostream &out) {
     DEBUG(status,out).print("save or unload is imminent; time to persist state\n");
 
-    // Call functions in the Persistence module here.
+    // Call functions in the Persistence module here. If your PersistantDataItem
+    // objects are already up to date, then they will get persisted with the
+    // save automatically and there is nothing extra you need to do here.
     return CR_OK;
 }
 
 DFhackCExport command_result plugin_load_data (color_ostream &out) {
     DEBUG(status,out).print("world is loading; time to load persisted state\n");
 
-    // Call functions in the Persistence module here.
+    // Call functions in the Persistence module here. See
+    // persistent_per_save_example.cpp for an example.
     return CR_OK;
 }
 

From b2a4f10c2292255f28ce607d670be912687b5787 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 3 Aug 2022 21:43:07 -0700
Subject: [PATCH 9/9] output onupdate log messages by default

but include info on how to make it stop
---
 plugins/examples/skeleton.cpp | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/plugins/examples/skeleton.cpp b/plugins/examples/skeleton.cpp
index e8553bdd6..539d84b1a 100644
--- a/plugins/examples/skeleton.cpp
+++ b/plugins/examples/skeleton.cpp
@@ -50,8 +50,8 @@ REQUIRE_GLOBAL(world);
 namespace DFHack {
     // for configuration-related logging
     DBG_DECLARE(skeleton, status, DebugCategory::LDEBUG);
-    // run `debugfilter set debug skeleton onupdate` to see logging in plugin_onupdate
-    DBG_DECLARE(skeleton, onupdate, DebugCategory::LINFO);
+    // for plugin_onupdate logging
+    DBG_DECLARE(skeleton, onupdate, DebugCategory::LDEBUG);
     // for command-related logging
     DBG_DECLARE(skeleton, command, DebugCategory::LDEBUG);
 }
@@ -138,7 +138,9 @@ DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_chan
 // Note that if the plugin implements the enabled API, this function is only called
 // if the plugin is enabled.
 DFhackCExport command_result plugin_onupdate (color_ostream &out) {
-    DEBUG(onupdate,out).print("onupdate called\n");
+    DEBUG(onupdate,out).print(
+        "onupdate called (run 'debugfilter set info skeleton onupdate' to stop"
+        " seeing these messages)\n");
 
     return CR_OK;
 }