refine docs, logging, help text

myk002 · myk002 · commit f400ee50f87b · 2022-08-15T16:15:41.000-07:00
diff --git 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
@@ -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
@@ -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;
 }
 

Original file line number	Diff line number	Diff line change
`@@ -119,7 +119,7 @@ DFhackCExport command_result plugin_load_data (color_ostream &out) {`
`119`	`119`	`}`
`120`	`120`
`121`	`121`	`DFhackCExport command_result plugin_onstatechange(color_ostream &out, state_change_event event) {`
`122`		`- if (event == DFHack::SC_MAP_UNLOADED) {`
	`122`	`+ if (event == DFHack::SC_WORLD_UNLOADED) {`
`123`	`123`	`if (is_enabled) {`
`124`	`124`	`DEBUG(status,out).print("world unloaded; disabling %s\n",`
`125`	`125`	`plugin_name);`