25.1.30

[Diggers]
* Completed converting entire game to new events system and removed last trace of an input polling procedure function (except for just joystick for now).
* Adjust up and down cursor sprite drawing co-ordinates.
* Implement converting joystick button presses to 'fake' mouse clicks and purge lots of obsolete code.
* Map joystick L1/2 and R1/2 to mouse scroll wheel functions.
* Clean-ups and optimisations.
* Scroll wheel will now cycle through inventory in-game.
* Improve error handler so the end-user can attempt to continue execution and not lose data. High chance in an engine input event handler, less so in any other event or engine main tick procedure.

[Assets]
* Update Diggers readme.

diggers/readme.md

@@ -146,13 +146,23 @@ Press `F1` at any time in the game to access the setup screen, `F2` to configure
 * **RESET**
   - Resets all the settings to default and applys the default values.
 * **BINDS**
-  - Show the configure binds screen.
+  - Show the keyboard binds configuration screen.
 * **ABOUT**
   - Show the acknowledgements.
 
 ## [Controls](#controls)…
-You can control the game with just a mouse which is novice difficulty like the Amiga computer and DOS version. Add use of the keyboard with the mouse makes the game quite easy to play. Playing with a controller is hard as it will basically emulate the mouse like the Amiga CD32 version of the game did.
+You can control the game with just a mouse which is novice difficulty like the Amiga computer and DOS version. Adding use of the keyboard alongside the mouse makes the game quite easy to play. Playing with a controller is hard as it will basically emulate the mouse like the Amiga CD32 version of the game did.
 
+### Basic controls
+All scenes out of the game will usually allow `any button` to select any point of interest which will normally be accompanied by a tooltip in the bottom-right hand corner of the screen and the `mouse wheel`, `L1`, `L2`, `R1` or `R2 game controller buttons` to cycle quickly through multiple choices on some screens.
+
+In-game, the `left mouse button` or `first game controller button` will select the point of interest under the cursor and the `right mouse button` or `second game controller button` will bring up a menu for the selected in-game object. Pressing the `START` button will pause and unpause the game.
+
+Pressing the `SELECT BUTTON` to enter the setup screen at any time.
+
+To see a complete keyboard shortcut listing, press the `F2` key at any time.
+
+### Cursors
 If you move the cursor and the cursor becomes anything but an arrow graphic, then than particular item on the screen is selectable, e.g.
 * 4 small arrows pointing to the centre…
   - Select/Perform action/Go here.
@@ -163,7 +173,7 @@ If you move the cursor and the cursor becomes anything but an arrow graphic, the
 * Arrow cursor pointing up/down/left or right…
   - Scroll.
 * A ticking clock…
-  - Control is blocked.
+  - All control is blocked temporarily.
 
 ### In-game hud…
 The hud is explained as follows from left to right…
@@ -190,68 +200,14 @@ The hud is explained as follows from left to right…
   - Question: Shows statistics and prediction information about the current zone operations.
   - Page: Displays the book.
 
-### Aliases…
-These aliases are for the explanations below. Note that keyboard defaults can
-be seen by pressing the F2 key (by default) and will not be listed here.
-
-| Alias | Meaning | Alias | Meaning |
-| --- | --- | --- | --- |
-| `MSE` | Refers to mouse | `JOY` | Refers to joystick |
-| `LMB` | Left-Mouse Button | `RMB` | Right-Mouse Button |
-| `MMB` | Middle-Mouse Button | `MWU` | Mouse Wheel up |
-| `MWD` | Mouse Wheel Down | `MBx` | Mouse Button `x` |
-| `JBx` | Joystick Button `x` | | |
-
-### Playstation controller aliases…
-| `JB0` | *Square* Button | `JB1` | *Cross* Button |
-| `JB2` | *Circle* Button | `JB3` | *Triangle* Button |
-| `JB4` | *L1* Button | `JB5` | *R1* Button |
-| `JB6` | *L2* Button | `JB7` | *R2* Button |
-| `JB8` | *Select* Button | `JB9` | *Start* Button |
-| `JB10` | *L3* Button | `JB11` | *R3* Button |
-
 ### Anywhere in the game (not configurable)…
-* `Alt`+`F4` on Windows or `Cmd`+`Q` on a Mac…
+* `Alt`+`F4` on Windows and Linux or `Cmd`+`Q` on a Mac…
   - Instant quit. Any game progress is lost but engine settings and ALREADY SAVED game progress will be written to disk in a `.udb` file.
 * `Alt`+`Enter`…
   - Switch between borderless or exclusive full-Screen and decorated window mode which will persist through app restarts.
 * `World`+`F` on a Mac…
   - Switch between native full-screen and decorated window mode which may persist through app restarts using native functionality. Using the MacOS options disables the `Alt`+`Enter` logic and you have to exit native full-screen mode to be able to use that shortcut again.
 
-### Anywhere in the game (but not during a fade transition…
-* `JB8`…
-  - Configure the game engine, video/audio settings, etc.
-* `JOY` or `MSE` axes…
-  - Move cursor on screen.
-* `JB1` or `LMB`…
-  - Select control under mouse cursor.
-
-### Intro or title credits…
-* `LMB` or `JB1`…
-  - Skip cut-scene/intro.
-
-### In-Level…
-* `START`…
-  - Pause the game.
-* `LMB` or `JB1`…
-  - Action, Select or Cancel menu.
-* `RMB` or `JB2`…
-  - Open menu for selected digger.
-
-### In-Level (paused)…
-* `JB3`+`JB4` or `MB3`+`MB4`…
-  - Forfeit the game only when paused (Game over).
-
-### Map Post-Mortem
-* `JB3`, `JB4`, `MB3` or `MB4`…
-  - Cycle between objects.
-
-### In-shop/Race select screen…
-* `MWU`, `MWD`, `JB4` or `JB5`…
-  - Scroll available options.
-* `JB1` or `LMB`…
-  - Select item under cursor.
-
 ## [Advanced](#advanced)…
 If for some reason you're an advanced-user or admin and need to fine tune how the game engine works, we have some command-line parameters that might be useful and you can overload as much as the operating system allows…
 

diggers/src/asset.lua

@@ -249,7 +249,9 @@ local aAssetsData<const> = {
       0, 330, 113, 182  -- [01] Stranger graphic
   } } },
   -- credit.lua ------------------------------------------------------------ --
-  credits = { T = 2, F = "vignette", P = { 0 } }
+  credits = { T = 2, F = "vignette", P = { 0 } },
+  -- setup.lua ------------------------------------------------------------- --
+  setupm = { T = 7, F = "setup" }
 };-- End ------------------------------------------------------------------- --
 -- Base code scripts that are to be loaded (don't modify the order)
 local aBaseScripts<const> = {

diggers/src/bank.lua

@@ -161,7 +161,7 @@ local function GoToLobby()
   SetKeys(true);
   SetHotSpot();
   -- Start the loading waiting procedure
-  SetCallbacks(GameProc, RenderInterface, nil);
+  SetCallbacks(GameProc, RenderInterface);
   -- Return to lobby
   InitLobby();
 end
@@ -238,7 +238,7 @@ local function OnAssetsLoaded(aResources)
   SetKeys(true, iKeyBankId);
   SetHotSpot(iHotSpotId);
   -- Set the callbacks
-  SetCallbacks(ProcLogic, ProcRender, nil);
+  SetCallbacks(ProcLogic, ProcRender);
 end
 -- Initialise the bank screen ---------------------------------------------- --
 local function InitBank()

diggers/src/book.lua

@@ -66,7 +66,7 @@ local function OnPageAssetsLoaded(aResource, fcbOnComplete)
   SetKeys(true, iKeyBankPageId);
   SetHotSpot(iHotSpotPageId);
   -- Run page loaded function
-  SetCallbacks(fcbProcLogic, ProcRenderPage, nil);
+  SetCallbacks(fcbProcLogic, ProcRenderPage);
 end
 -- Page loader function ---------------------------------------------------- --
 local function LoadPage(fcbOnComplete)
@@ -132,7 +132,7 @@ local function GoOpen()
   SetKeys(true, iKeyBankPageId);
   SetHotSpot(iHotSpotPageId);
   -- Set main page game proc
-  SetCallbacks(fcbProcLogic, ProcRenderPage, nil);
+  SetCallbacks(fcbProcLogic, ProcRenderPage);
 end
 -- Set render background function ------------------------------------------ --
 local function ProcRenderBackInGame()
@@ -156,15 +156,15 @@ local function OnPageAssetsPostInGame()
   SetKeys(true, iKeyBankStartId);
   SetHotSpot(iHotSpotStartId);
   -- No transition from in-game
-  SetCallbacks(GameProc, fcbProcRenderCover, nil);
+  SetCallbacks(GameProc, fcbProcRenderCover);
 end
 -- Cover data loaded? ------------------------------------------------------ --
 local function OnPageAssetsPostLobbyFadedIn()
   -- Set intro page and hot spots keys
   SetKeys(true, iKeyBankStartId);
   SetHotSpot(iHotSpotStartId);
   -- Return control to main loop
-  SetCallbacks(nil, fcbProcRenderCover, nil);
+  SetCallbacks(nil, fcbProcRenderCover);
 end
 -- Cover loaded in-lobby supplimental callback ----------------------------- --
 local function OnPageAssetsPostLobby()
@@ -178,7 +178,7 @@ local function ExitInGame()
   -- Dereference assets for garbage collector
   texPage, texBook = nil, nil;
   -- Start the loading waiting procedure
-  SetCallbacks(GameProc, RenderInterface, nil);
+  SetCallbacks(GameProc, RenderInterface);
   -- Continue game
   InitContinueGame(true);
 end

diggers/src/cntrl.lua

@@ -106,7 +106,7 @@ local function OnFadedIn()
   SetKeys(true, iKeyBankId);
   SetHotSpot(iHotSpotId);
   -- Set controller callbacks
-  SetCallbacks(ProcLogic, ProcRender, nil);
+  SetCallbacks(ProcLogic, ProcRender);
 end
 -- When controller resources have loaded? ---------------------------------- --
 local function OnAssetsLoaded(aResources)
@@ -184,18 +184,17 @@ end;
 -- Scripts have been loaded ------------------------------------------------ --
 local function OnScriptLoaded(GetAPI)
   -- Functions and variables used in this scope only
-  local RegisterHotSpot, RegisterKeys, SetCursor, aAssetsData, aCursorIdData,
-    aSfxData;
+  local RegisterHotSpot, RegisterKeys, aAssetsData, aCursorIdData, aSfxData;
   -- Grab imports
   Fade, InitBook, InitFile, InitLobby, InitMap, InitRace, LoadResources,
     PlayStaticSound, RegisterHotSpot, RegisterKeys, RenderShadow,
-    RenderTipShadow, SetCallbacks, SetCursor, SetHotSpot, SetKeys,
-    aAssetsData, aCursorIdData, aGlobalData, aSfxData, fontSpeech =
+    RenderTipShadow, SetCallbacks, SetHotSpot, SetKeys, aAssetsData,
+    aCursorIdData, aGlobalData, aSfxData, fontSpeech =
       GetAPI("Fade", "InitBook", "InitFile", "InitLobby", "InitMap",
         "InitRace", "LoadResources", "PlayStaticSound", "RegisterHotSpot",
         "RegisterKeys", "RenderShadow", "RenderTipShadow", "SetCallbacks",
-        "SetCursor", "SetHotSpot", "SetKeys", "aAssetsData", "aCursorIdData",
-        "aGlobalData", "aSfxData", "fontSpeech");
+        "SetHotSpot", "SetKeys", "aAssetsData", "aCursorIdData", "aGlobalData",
+        "aSfxData", "fontSpeech");
   -- Set assets data
   aAssets = { aAssetsData.lobbyc, aAssetsData.cntrl };
   -- Set sound effect ids

diggers/src/credit.lua

@@ -180,7 +180,7 @@ local function ProcCreditsLogic()
   iActionTimer = iActionTimer + 1;
   if iActionTimer < 600 then return end;
   -- Keep rendering text during blackout loading
-  SetCallbacks(nil, nil, nil);
+  SetCallbacks(nil, nil);
   -- If this is the last credit?
   if bLast then
     return Fade(0, 1, 0.04, fcbCreditsRender, InitRollingCredits);

diggers/src/data.lua

@@ -159,11 +159,11 @@ local CID<const> = {
 -- Cursor data ------------------------------------------------------------- --
 local aCursorData<const> = {
   -- CID ------- S - C - X  Y ---- CID ------- S - C - X  Y ---
-  [CID.ARROW] ={ 992,  1, 0, 0}, [CID.OK]    ={1005,  4,-7,-8},
-  [CID.EXIT]  ={1001,  4,-7,-8}, [CID.LEFT]  ={ 997,  1,-7,-7},
-  [CID.TOP]   ={ 998,  1,-7,-7}, [CID.RIGHT] ={ 999,  1,-7,-7},
-  [CID.BOTTOM]={1000,  1,-7,-7}, [CID.SELECT]={ 993,  4,-7,-7},
-  [CID.WAIT]  ={ 960,  8,-7,-7}, [CID.NONE]  ={1009,  1, 0, 0},
+  [CID.ARROW] ={ 992,  1, 0,  0}, [CID.OK]    ={1005,  4,-7,-8},
+  [CID.EXIT]  ={1001,  4,-7, -8}, [CID.LEFT]  ={ 997,  1,-7,-7},
+  [CID.TOP]   ={ 998,  1,-7,  0}, [CID.RIGHT] ={ 999,  1,-7,-7},
+  [CID.BOTTOM]={1000,  1,-7,-15}, [CID.SELECT]={ 993,  4,-7,-7},
+  [CID.WAIT]  ={ 960,  8,-7, -7}, [CID.NONE]  ={1009,  1, 0, 0},
   -- CID ------- S - C - X  Y ---- CID ------- S - C - X  Y ---
 };
 -- Object flags ------------------------------------------------------------ --
@@ -2654,54 +2654,92 @@ local aCreditsXData<const> = {
   { "Thank you for playing!",          "The End!" },
 };
 -- Setup buttons data ------------------------------------------------------ --
-local aSetupButtonData<const> = { -- nil's are filled in 'setup.lua' init
-  APPLY = { nil, nil, nil, nil, CID.OK,   nil, 101, nil, nil,
-    "CLICK TO APPLY ANY SYSTEM AFFECTING SETTINGS YOU HAVE CHANGED" },
-  DONE  = { nil, nil, nil, nil, CID.EXIT, nil, 102, nil, nil,
-    "CLICK TO EXIT THIS SETUP WINDOW AND RETURN TO YOUR GAME. ANY CHANGED \z
-     SETTINGS THAT NEED TO BE APPLIED WILL BE CANCELLED" },
-  RESET = { nil, nil, nil, nil, CID.OK,   nil, 103, nil, nil,
-    "CLICK TO RESET ALL VALUES TO DEFAULTS AND AUTOMATICALLY APPLY THE \z
-     SETTINGS" },
-  BINDS = { nil, nil, nil, nil, CID.OK,   nil, 104, nil, nil,
-    "CLICK TO CHANGE KEYBINDS FOR THIS GAME" },
-  ABOUT = { nil, nil, nil, nil, CID.OK,   nil, 105, nil, nil,
-    "CLICK TO VIEW THE ACKNOWLEDGEMENTS FOR THIS GAME" },
+local aSetupButtonData<const> = {
+  -- -- Legend ------------------------------------------------------------- --
+  -- [*1] Unique hot spot template.    [!2] Unique tip id.
+  -- [*3] X text position.             [*4] Y text position.
+  -- [!5] Button text.                 [!6] Scrolling text information tip.
+  -- ! = static, * = Filled in at setup.lua > OnScriptLoaded() function.
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.EXIT, false, false, false }, 101, nil, nil,
+    "CLOSE", "CLOSE THIS CONFIGURATION DIALOG AND RETURN TO THE GAME. YOU \z
+     WILL LOSE ANY SYSTEM AFFECTING CHANGES THAT REQUIRE THE 'APPLY' BUTTON \z
+     TO BE CLICKED" },
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.OK, false, false, false }, 101, nil, nil,
+    "APPLY", "CLICK TO APPLY ANY SYSTEM AFFECTING SETTINGS YOU HAVE CHANGED" },
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.OK, false, false, false }, 103, nil, nil,
+    "RESET", "CLICK TO RESET ALL VALUES TO DEFAULTS AND AUTOMATICALLY APPLY \z
+     THE SETTINGS" },
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.OK, false, false, false }, 104, nil, nil,
+    "BINDS", "CLICK TO CHANGE KEYBINDS FOR THIS GAME" },
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.OK, false, false, false }, 105, nil, nil,
+    "ABOUT", "CLICK TO VIEW THE ACKNOWLEDGEMENTS FOR THIS GAME" },
 };-- Setup options data ---------------------------------------------------- --
-local aSetupOptionData<const> = { -- nil's are filled in 'setup.lua' init
-  -- Option name -- Value -- UpdateFunc --- DownFunc --- UpFunc ------------ --
-  { "Monitor",         "", nil,           nil,         nil,
+local aSetupOptionData<const> = {
+  -- -- Legend ------------------------------------------------------------- --
+  -- [*1] Unique hot spot template.    [*2] Update text value [7] callback.
+  -- [*3] Y position of text line.     [*4] X position of left justified text.
+  -- [!5] Category text.               [*6] X position of right justified text.
+  -- [*7] Value text.                  [!8] Scrolling text information tip.
+  -- ! = static, * = Filled in at setup.lua > OnScriptLoaded() function.
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Monitor",         0, "",
     "CHANGES THE MONITOR THE GAME WILL APPEAR ON BY DEFAULT. PRESS APPLY \z
      WHEN YOU ARE HAPPY WITH THE SELECTION TO ACTIVATE IT", },
-  { "Display State",   "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Display State",   0, "",
     "CHANGES THE DEFAULT WINDOW STYLE OF THE GAME. PRESS APPLY WHEN YOU ARE \z
      HAPPY WITH THE SELECTION TO ACTIVATE IT" },
-  { "Full-Resolution", "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Full-Resolution", 0, "",
     "ALLOWS YOU TO SET A CUSTOM DESKTOP RESOLUTION FOR EXCLUSIVE FULL-SCREEN \z
      MODE. PRESS APPLY WHEN YOU ARE HAPPY WITH THE SELECTION TO ACTIVATE IT" },
-  { "Window Size",     "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Window Size",     0, "",
     "ALLOWS YOU TO SET A CUSTOM WINDOW SIZE FOR DECORATED WINDOW ONLY MODE. \z
      PRESS APPLY WHEN YOU ARE HAPPY WITH THE SELECTION TO ACTIVATE IT" },
-  { "Frame Limiter",   "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Frame Limiter",   0, "",
     "ALLOWS YOU TO CHOOSE FROM A RANGE OF FRAME-LIMITING OPTIONS TO BALANCE \z
      THE PERFORMANCE VERSUS POWER USAGE OF RENDERING. SOME VALUES MAY BE \z
      INEFFECTIVE WHEN THE VSYNC VALUE IS BEING OVERRIDDEN IN YOUR VIDEO \z
      ADAPTER SETTINGS OR WHEN YOUR SYSTEM IS UNDERPERFORMING. THE CHANGE IS \z
      INSTANTLY APPLIED" },
-  { "Texture Filter",  "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Texture Filter",  0, "",
     "APPLY A BILINEAR UPSCALE FILTER TO THE MAIN FRAMEBUFFER. THE GAME IS \z
      RENDERED IN 320x240. THE CHANGE OF OPTION IS INSTANTLY APPLIED" },
-  { "Audio Device",    "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Audio Device",    0, "",
     "ALLOWS YOU TO SET THE DEFAULT AUDIO DEVICE TO USE FOR THE GAME. PRESS \z
      APPLY WHEN YOU ARE HAPPY WITH THE SELECTION TO ACTIVATE IT" },
-  { "Master Volume",   "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Master Volume",   0, "",
     "CHANGES THE FINAL OUTPUT VOLUME OF ALL MUSIC, SOUND EFFECTS AND FMV \z
      MIXED TOGETHER. THE CHANGE OF OPTION IS INSTANTLY APPLIED" },
-  { "Music Volume",    "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Music Volume",    0, "",
     "CHANGES THE MUSIC VOLUME. THE CHANGE OF OPTION IS INSTANTLY APPLIED" },
-  { "Effect Volume",   "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Effect Volume",   0, "",
     "CHANGES THE SFX VOLUME. THE CHANGE OF OPTION IS INSTANTLY APPLIED" },
-  { "Fmv Volume",      "", nil,           nil,         nil,
+  -- ----------------------------------------------------------------------- --
+  { { nil, nil, nil, nil, 0, CID.SELECT, false, false, false },
+    false, 0, 0, "Fmv Volume",      0, "",
     "CHANGES THE FMV VOLUME. THE CHANGE OF OPTION IS INSTANTLY APPLIED" },
 };-- Option name -- Value -- UpdateFunc --- DownFunc --- UpFunc ------------ --
 local aIntroSubTitles<const> = {

diggers/src/debug.lua

@@ -418,7 +418,7 @@ local function InitDebugPlay(iId)
       end
     end
     -- Set real function
-    SetCallbacks(OnTickRandom, fcbRCallback, nil);
+    SetCallbacks(OnTickRandom, fcbRCallback);
   end
   if iId then
     fcbTCallback, fcbRCallback = OnTick, OnRender;