Write out Hidden System Design

code/player_management.lua

@@ -6,7 +6,7 @@
 -- managing player hidden values via mod storage.           --
 -- For example:                                             --
 --                                                          --
--- When a category is hidden by default, and a plyer has    --
+-- When a category is hidden by default, and a player has   --
 -- somehow unlocked that category or entry, they will have  --
 -- an entry in their player table specifying as such.       --
 --                                                          --
@@ -18,6 +18,9 @@
 -- Nothing happens in this file if the hidden system is     --
 -- disabled, as it's un-needed to track per-player data.    --
 --                                                          --
+-- Persistence is handled by storing each player's data     --
+-- by name in the world folder under "game_doc/<name>.json" --
+--                                                          --
 -- Note: if you have a player reveal a hidden entry, and    --
 -- then you remove that entry for some reason, they will    --
 -- have a memory leak here where we track that hidden value --
@@ -25,6 +28,13 @@
 -- returned, the old player value will be remembered.       --
 --------------------------------------------------------------
 
+--------------------------
+--
+-- load_player
+--
+-- Load the
+--
+
 --------------------------
 --
 -- on_joinplayer

design.md

@@ -69,6 +69,89 @@ Documentation hypertext in the top
 1. At any time, if exscape is pressed, just let them leave
 2. Always start them at the top level formspec
 
+# Hidden System Design
+
+## Note about loading player tables
+
+If the .json loaded is invalid, Error out and stop loading the server,
+alert the user to which .json
+
+Ignore any entries or categories that the player has that aren't even entries or
+categories, the server owner may re-enable them later. 
+
+## Startup
+
+1. Parse all the entries at on_load into a default hidden table
+2. Load the previous table of default hidden categories and entries
+3. Build a table of those (categories and entries) that are changed since last time (all of them if first execution)
+    - If any are changed, load and change ALL player entries to be up to date
+
+## On-Join-Player
+
+When a player joins, load their saved "shown" values
+    - If they have none, use the defaults
+    - All values are assumed to be HIDDEN by default, so this runtime player table will only have the to be shown values:
+```lua
+player_data[player_name].shown_categories = {
+    "cat1",
+    "cat2",
+    "cat3",
+    "cat4",
+}
+player_data[player_name].shown_entries = {
+    ["cat1"] = { "ent1", "ent2", },
+    ["cat2"] = { "ent1", "ent2", },
+}
+```
+
+This will require some processing to find out if a player has something hidden that is normally shown, as you must compare
+the *missing* saved "hidden" category/entry with the default "shown" category/entry and make sure to save the player actually 
+*doesn't* have that shown (like it would be by default).
+
+Finally Sort the shown_categories list and the shown_entries sub-lists
+
+## On-Leave-Player
+
+Make the runtime player table equal to nil:
+```lua 
+player_data[player_name] = nil
+```
+For keeping down memory usage :)
+
+## Display 
+
+1. When a player loads up the main_form(), use the shown_categories for the player list
+2. When a player loads up a category_form, use the shown_entires for the player list
+3. When they try to view a hidden category OR entry, instead take them to the main_form
+
+## Modifications
+
+```lua
+function on_modification(player_name)
+    local hidden_table = nil
+    if player_is_logged_in then
+        update their runtime lists() (and sort)
+        if no_change() then
+            return
+        end
+        invalidate_their_currently_displayed_entry&category&form()
+
+        hidden_table = player_table
+    else
+        if minetest.builtin_auth_handler.get_auth(player_name) == nil then
+            return
+        else
+            hidden_table = calculate_effects_of_defaults_on_load(load_values(player_name))
+            update_the_table(hidden_table)
+        end
+    end
+
+    -- Made it this far, time to save
+    calculate_effects_of_defaults_on_save(hidden_table)
+    save_as_json(hidden_table, player_name) --will not save nil table
+end
+```
+
 
 
 

init.lua

@@ -25,13 +25,6 @@
 ---- <> code/direct_access.lua:
 ----      Provides the 2 modder-facing game_doc direct access functions
 ----      Note: changes made in these tables will affect the game, they are NOT copies
-----
----- <> code/formspecs.lua:
-----      Generates the 3 different formspecs (main, category, and entry) for this in-game documentation/text system
-----
----- <> code/integration.lua:
-----      Based on settings, will register the command /game_doc to show the main documentation menu
-----      and will, if found, add a tab to i3 to access the same formspec from the inventory screen.
 ---- 
 ---- <> code/player_management.lua:
 ----      As player's join the game for the first time, and have their hidden values updated,
@@ -39,6 +32,13 @@
 ----
 ---- <> code/hidden_modifications.lua:
 ----      Provides the 4 modder-facing game_doc hidden-modification functions
+----
+---- <> code/formspecs.lua:
+----      Generates the 3 different formspecs (main, category, and entry) for this in-game documentation/text system
+----
+---- <> code/integration.lua:
+----      Based on settings, will register the command /game_doc to show the main documentation menu
+----      and will, if found, add a tab to i3 to access the same formspec from the inventory screen.
 
 
 -- Global main mod table