rework mesecons debug to be more flexible (#7)

* add proper settings (untested)

* more constants -> settings

* normalize whitespace between code files

* refactor globalsteps in order to simplify logic

* minor refactoring

* rename file

* use mod_storage for persistent data; optimize context initialization

* refactoring (moving files around)

* rewrite penalty

* add settings; document; allow changing while game is running

* add command to update settings

* update init after splitting commands into files

* fix bugs; add debugging tools; too much for one commit...

* fix whitelist conversion

* add adjustable blinky plant to timer overrides

* add some more mesecons nodes with repeating timers

* resolve luacheck warnings

* tweak hud

* Update documentation; parameterize more things; refactor some logic for readability

1 files changed, 79 insertions, 17 deletions

diff --git a/README.md b/README.md
index b289345..8e066f5 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,61 @@
 # Mesecons Debug Collection
 
-Allows to throttle mesecons activity per mapblock
+Throttles mesecons if the server is lagging, in particular when mesecons is causing the lag. 
 
 # Overview
 
-There is a cpu quota for every mapblock, if that quota is used up
-the mesecons contraptions will be slowed down for that mapblock
+This mod can penalizes mesecons activity on a per-mapblock basis, which can help laggy or machine-heavy servers
+to be less laggy overall. Penalties are implemented as delays on various events. 
 
-The current mapblock-stats can be viewed with `/mesecons_hud on`
+Lag and per-mapblock mesecons usage are tracked over time, in order to calculate how much to penalize each
+mapblock, or whether to reduce the penalty. 
+
+The mod defines 3 regimes of lag, with different scales of penalties. 
+
+* If the server steps are not taking much longer than the time allotted for them, the "low penalty" regime will apply.
+* If the server steps are taking too long on average, and mesecons usage isn't particularly high, the "medium penalty" 
+  regime will apply.
+* If the server steps are taking too long on average and mesecons usage is high, or the server steps are taking much too
+  long to execute, the "high penalty" regime will apply. 
+
+Each of these regimes has an associated "scale" and "offset". Every time the penalties are re-evaluated, 
+they are changed according to this formula:
+
+```lua
+    new_penalty = old_penalty + (relative_load * penalty_scale) + penalty_offset
+```
+
+Here, relative_load is the ratio of how much time the current mapblock spends doing mesecons, to the mean time 
+(spent doing mesecons) across all mapblocks currently running mesecons. This value is currently clamped between 0.1
+and 10, to prevent certain edge cases from being penalized too rapidly. A value of 10 would mean that the mapblock 
+under consideration is using 10x as much mesecons as the average mapblock.
+
+Note that, depending on the values of `penalty_scale` and `penalty_offset`, the new penalty may be *less* than the old
+penalty. This is to allow penalties to reach equilibrium under a constant load, and to taper off over time if the
+usage in the mapblock declines, or the regime changes. 
 
 ## Settings
 
-* `mesecons_debug.max_usage_micros` default: 15000
+* `penalty_clear_cooldown = 120` Seconds that a player has to wait between using the `mesecons_clear_penalty` command
+* `max_penalty = 120` Upper limit of the per-mapblock penalty
+* `penalty_mapblock_disabled = 110` 
+  Completely disable mesecons in a mapblock, if the penalty exceeds this value.
+  Set above `max_penalty` to disable this feature. 
+* `penalty_check_steps = 50` # of server steps between updating the penalties
+* `gc_interval = 61` Seconds after which data about unloaded mapblocks is removed from memory. 
+* `hud_refresh_interval = 1` Seconds between updating the client's HUD
+* `moderate_lag_ratio = 3`
+  Ratio between actual and expected length of a server step at which lag is considered "moderate"
+* `high_lag_ratio = 9` Ratio between actual and expected length of a server step at which lag is considered "high"
+* `high_load_threshold = 0.33` 
+  % of processing a server spends on mesecons at which the mescons load is considered "high".
+* `low_penalty_offset = -1` Offset of the penalty in the low-lag regime.
+* `low_penalty_scale = 0.1` 
+  Scale of the penalty in the low-lag regime. The default values ensure that nothing is penalized in the low-lag regime.
+* `medium_penalty_offset = -0.8` Offset of the penalty in the moderate-lag regime.
+* `medium_penalty_scale = 0.2` Scale of the penalty in the moderate-lag regime.
+* `high_penalty_offset = -0.5` Offset of the penalty in the high-lag regime.
+* `high_penalty_scale = 0.5` Scale of the penalty in the high-lag regime. 
 
 ## Privs
 
@@ -19,21 +63,39 @@ The current mapblock-stats can be viewed with `/mesecons_hud on`
 
 ## Commands
 
+* `/mesecons_clear_penalty` 
+    Clears the penalty for the current mapblock. Users can only execute this every `penalty_clear_cooldown` seconds
+* `/mesecons_global_stats` shows the mapblock with the most prominent usage of mesecons activity
+* `/mesecons_hud` toggles the hud
+* `/mesecons_stats` shows some mesecons stats for the current position
+
+
+### Admin Commands
+
 All of these commands require the `mesecons_debug` privilege.
 
-* `/mesecons_hud [on|off]` enables or disables the hud
-* `/mesecons_flush` Flushes the action queue
-* `/mesecons_enable` Enable the mesecons queue
-* `/mesecons_disable` Disables the mesecons queue
-* `/mesecons_stats` shows some mesecons stats for the current position
-* `/mesecons_global_stats` shows the mapblock with the most prominent usage of mesecons activity
-* `/mesecons_whitelist_get` shows the list of whitelisted mapblocks
+* `/create_lag <microseconds> <chance>` 
+   Artificially slow down the server by `microseconds` every `chance` server steps. Useful for debugging this mod.
+* `/mesecons_debug_get <setting>` Inspect the current value of a setting.
+* `/mesecons_debug_set <setting> <value>` Change a setting value. This does *not* save the value between reboots! 
+* `/mesecons_disable` Disables mesecons entirely
+* `/mesecons_enable` Undoes the above command
+* `/mesecons_flush` Flushes the mesecons action queue
 * `/mesecons_whitelist_add` adds the current mapblock to the whitelist
+* `/mesecons_whitelist_get` shows the list of whitelisted mapblocks
 * `/mesecons_whitelist_remove` removes the current mapblock from the whitelist
 
-## Penalty controller
+## Nodes
+
+### Mesecons Lagger
+
+A node which can create `n` microseconds of lag once every `chance` server steps. Useful for debugging this mod.  
+
+### Penalty Controller
+
+Requires the `digiline` mod.
 
-Can query the penalty and usage values of the placed-in mapblock (requires the `digiline` mod)
+Can query the penalty and usage values of the mapblock it is placed in.
 
 Example code to query it with the luacontroller:
 
@@ -45,9 +107,9 @@ end
 if event.type == "digiline" and event.channel == "penalty_ctrl" then
   --[[
   event.msg = {
-    micros = 0,
-    avg_micros = 0,
-    penalty = 0,
+    micros     = 0, -- micros_per_second
+    avg_micros = 0, -- avg_micros_per_second
+    penalty    = 0, -- in seconds
     whitelisted = false
   }
   --]]