support dynamic onupdate frequency adjustments

set to 0 for an immediate burst of high frequency calls

docs/changelog.txt

@@ -61,6 +61,7 @@ Template for new versions:
 ## Fixes
 
 ## Misc Improvements
+- `overlay`: allow ``overlay_onupdate_max_freq_seconds`` to be dynamically set to 0 for a burst of high-frequency updates
 
 ## Documentation
 

docs/dev/overlay-dev-guide.rst

@@ -135,7 +135,10 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
     seconds) that your widget can take to react to changes in information and
     not annoy the player. Set to 0 to be called at the maximum rate. Be aware
     that running more often than you really need to will impact game FPS,
-    especially if your widget can run while the game is unpaused.
+    especially if your widget can run while the game is unpaused. If you change
+    the value of this attribute dynamically, it may not be noticed until the
+    previous timeout expires. However, if you need a burst of high-frequency
+    updates, set it to ``0`` and it will be noticed immediately.
 
 Registering a widget with the overlay framework
 ***********************************************

plugins/lua/overlay.lua

@@ -433,8 +433,12 @@ end
 -- reduces the next call by a small random amount to introduce jitter into the
 -- widget processing timings
 local function do_update(name, db_entry, now_ms, vs)
-    if db_entry.next_update_ms > now_ms then return end
     local w = db_entry.widget
+    if w.overlay_onupdate_max_freq_seconds ~= 0 and
+        db_entry.next_update_ms > now_ms
+    then
+        return
+    end
     db_entry.next_update_ms = get_next_onupdate_timestamp(now_ms, w)
     if detect_frame_change(w, function() return w:overlay_onupdate(vs) end) then
         if register_trigger_lock_screen(w:overlay_trigger(), name) then