Maintenance update!

Currently no big changes because I am still adjusting to the freshly hatched crabling that joined my family recently.

A new frequently requested submod will be tested on a large server soon.

BTSE_Base:
- moved the UI options button to the top left of the UI so people who set the UI scale to some crazy value should be able to reset the scaling regardless
- a few under the hood stability changes

BTSE_Economy:
- added new vehicle shop thumbnails, refreshed some existing ones

BTSE_Tools:
- the `/leaflets` command and its UI gadget will now "place" instead of "drop" items to prevent world cleanup from removing the items

BTSE_Base:
- replaced calls to vanilla modal windows within btse with my own so they scale and look proper because i kept getting reports about the vanilla ones not scaling with various screen / font sizes. the new windows are: info window, yes / no prompt, text prompt, long text prompt, number prompt
- when a player list is populated and a player is invisible they are marked locally as invisible person and omitted from all BTSE UI player lists from that point on, regardless of their actual invisibility status in the future. staff members can still see everyone in those lists. this was made to prevent players from tracking if admins were watching them.
- added internal client / server command buffer for those sent within BTSE. this will stagger commands to a maximum of 10 per second instead of bursting them at times so the communication between server and client is more fluent and reliable.
- removed the sandbox option and functionality for square load buffering because the game keeps removing objects while they are being looped over and i got tired of seeing the same resulting error being posted over and over
- changed the way square load event hooks are executed
- things being made unbreakable via `PARP.Movables:setUnbreakable` will now be handled a bit differently
- `PARP:registerCallback()` now accepts a timeout in seconds and an error message in case there is no `btse.executeCallback` called within the timeframe
- `btse.executeCallback` will now pass the command arguments to the handler function
- gadget panels can now listen to the handler `onActivatePanel` in their config. it will be fired when the panel is made visible and gets an instance of the panel as parameter to make the gadget UI more responsive. changed existing components to use this instead of the tab activation handler.
- added a player database feature that can be used to keep track of some useful player data when they log in. it uses global moddata on the server and is inactive by default except when explicitly enabled by setting `BTSE.UserDB["enabled"] = true;` within `lua/shared` up until the point where the `OnInitGlobalModData` is fired. if active, data can be fetched from server via `BTSE.UserDB:getUserData(username)` and will fire a client side hook called `userDBEntryReceived` with the parameters `username, data, modDataKey`. it is advised not to make use of this because some core functionality will likely change in the next version.
- various changes and improvements to about 20 BTSE UI component classes that nobody will read anyway
- some new UI components, including a username picker
- added some more abstraction for item related actions with b42 in mind
- moved a lot of functions around within some files so they make more sense. some were refactored to fit different namespaces. existing code should not be affected because of wrappers.
- various under the hood improvements

BTSE_Chat:
- event teleports are now staggered in 5 second intervals to reduce the load on the server when pulling participants to a location

BTSE_Economy:
- added 2060 shop pictures for all current vanilla and KI5 vehicles
- added a new gadget for automatically taking shop pictures from within the current server environment. if you're missing screenshots for your shop and want them to be the same as the bundled ones, use this one. there are no guarantees they'll come out perfect but it beats retaking them yourself
- various item related factors are now counted towards pricing on exchange. freshness of produce, condition, amount left and percentage eaten. those modifiers are cumulative so if you're selling a 25% eaten stale cabbage you get 50% off for it being stale and 75% for the eaten percentage, resulting in 37.5% of the price of a fresh cabbage.
- if an equipped weapon is exchanged for money at an ATM it will now be force unequipped to prevent unwanted interaction with mods that will replace an item with another on key press and basically create a free new instance of the item to sell again
- adjusted UI and valuables list / exchange code to account for the display of conditions
- local display of the account balance is now more reliable when changes to the account happen and the UI is open. this eliminates the need to "double tap", reducing the amount of commands sent to clients
- valuables exchange commands to the server are now staggered
- opening a shop tab will now show a load mask to show users that the short freeze is the shop item cache being generated
- when opening the general BTSE UI, the valuables lists are not updated automatically anymore. it has become an issue with people having hundreds if not thousands of items in their pockets that the game can freeze. now the list is updated when the player opens the tab and it shows a load mask informing them about the issue.
- removed sandbox option for max vehicle thumbnail size (obsolete because of UI)
- changed the way thumbnails for vehicle shop entries are searched. checks shop item config, then "_0" skin file, then plain vehicle script name
- added an explanation to the "set price" window so people stop asking why tagging is so slow
- the "look for shops" button for when the game desyncs shop tile data now searches 100 tiles around the player
- added more user error tolerance to the "get vehicle picture" method being used for the shop UI

BTSE_Examples:
- added more code to prevent the files inside being executed by pz because people keep copying the whole example mod instead of the files inside, expecting their server to not have issues after it. do not copy the whole mod!

BTSE_RestorePods:
- the "light" variant of the player dump data list is now a bit lighter in case you've got a large amount of retained skill dumps set or there is some sweatlord whose info dumps exceed 32kb, crashing pz's sendClientCommand
- if player data becomes corrupted (e.g. due to favoriting "rip clothes" with many clothes mods) the resulting [None None] character dump will be rejected to preserve what was still there before the corruption. this will be logged to `Lua/btse_death_restore/error.log` on the server
- refactored server side code into multiple command files to make it easier for me to find stuff

BTSE_Tools:
- removed leftover debug logging

Global:
- all occurrences of item instantiation have been abstracted in anticipation of the item spawn changes for b42
- removed all `versionMax` occurrences from `mod.info` files

BTSE_Base:
- corrected a missing translation for "nothing to do" in the ui
- onActivateTab handler for gadgets now receives the tab and the subcomponent
- various smaller changes / optimizations under the hood

BTSE_Economy:
- fixed the "tax receiver" field not being writable in the vending machine firmware update window
- added a fallback distance to the shop distance check in case of invalid object data, outdated object cache or invalid sandbox data

BTSE_RestorePods:
- default item is now not a tandy from `BTSE_Chat` anymore. this was forgotten during testing and should not affect anyone.

BTSE_Base:
- "manage players" ui will not throw an error anymore when no player tools are loaded. the tab itself will still be shown because it is useful for finding out the full names of connected players.

BTSE_Economy:
- changed translation "Currencies hidden in balance output" in sandbox options to exclude the "/balance" because it affects the balance output in the UI too

BTSE_Tools:
- re-added the item batch spawner as a gadget (thanks for reminding me, Fallen Seraph!)

NEW SUBMOD! BTSE_RestorePods:
the text was too much for this changelog so i created a discussion post (click to open) describing what it does.

A huge "THANK YOU" goes out to KI5 yet again for creating the pod sprites (and all the other BTSE spritework for that matter), the bazillion numbers and graffiti drawings i tortured him with!

Multiple "thank you"s go out to the following communities (in order of implementation) for testing, various ways of support and feedback: Project Apocalypse, A Path Above and Dawn of the Dead!

UI:
- the player list component now sorts by lowercase text so the lowercase names won't be at the bottom anymore
- if a player list component is set up to show usernames it will be sorted by username, if not then by first / last name
- if the resulting UI height after scaling calculations would be larger than the user's screen resolution height then the settings "scale by percentage" and 75% scaling will be force applied
- changed options slider label "Main UI transparency" to "Main UI alpha"
- data views now apply the same alpha settings applied for the UI, so if you set 50% alpha the tiles will be 50% on top of 50% of the main UI. this mostly affects the home screen, shops and tile picker
- the "manage players" section will now be refreshed when the mini scoreboard is refreshed, not just the big one. the list will try to keep the selected user active and jump to the first one if the previously selected user logged out
- adjusted the height of elements within various tabs because of them getting out of line with different font scaling options

BTSE_Base:
- tried to improve the code of the collection processing helpers via pcall and additional checks which should help when pz removes an object during processing
- fixed `PARP:getObjectSpriteName` throwing an error when an object sprite was invalid

BTSE_Chat:
- moved registration of custom chat commands from `OnChatWindowInit` to `OnInitGlobalModData`

BTSE_Economy:
- because things are how they are with pz, font sizes, scaling and low resolution / large font size combos, the money management UI is now small size compatible and lacks the overview it once had for proper desktop resolutions
- the context menu options for the shops are now always enabled when right clicking vending machines / shop terminals because the tabs are always accessible anyway and the buy button status decides if a sale is possible
- inventory items that were favorited at the time the exchange window was opened will not show in the list of valuables on your person so your favorites aren't destroyed when things are sold without checking the list first
- shop tab buy buttons now show a tooltip telling the user they need to select an entry to the left before trying to buy things. until now it was the "you need to get closer to a shop" one
- added a button to the shop UIs that allows you to rescan the immediate vicinity for economy tiles in case the tile cache didn't pick up on the shop that the user is currently trying to use
- moved registration of custom chat commands from `OnChatWindowInit` to `OnInitGlobalModData`
- possibly fixed a rare issue where a desynced character does not know where they are in a distance check. it's rare, so it's hard to reproduce.

BTSE_Locks:
- added a check for invalid object references in `BTSE.Locks:objectIsSecurityWall`
- added some checks and logging for invalid wall sprite properties within `BTSE.Locks:rebuildDoorIfNecessary`
- if a sprite does not have "getNorth" as function `BTSE.Locks:rebuildDoorIfNecessary` will try to read the destroyed door sprite properties "doorN" / "doorW" and assume north
- might play better with garage doors but the game still hates them so i don't know

BTSE_Tools:
- the "dump player list" gadget now adds line breaks between the entries displayed in the text area
- moved registration of custom chat commands from `OnChatWindowInit` to `OnInitGlobalModData`

to the users with small screens and / or custom font sizes:

i tried to find a way to tell the game to use a specific font size but did not find any. if you set a font size in the options then the "small", "medium" and other fonts are given different font source files and the default ones become unavailable. this means i can't just tell the game to draw text in the original pz font size. the best i could do with this UI was to respect the user setting for font size in their game options and to base the position and size calculations off their choice for a more consistent look across resolutions. if your font size selection makes it impossible for the ui to be drawn properly because it is too large the only hope you have is to change the scaling in the ui options back to a smaller size which will likely look bad. i will be looking into this further but i can't promise that i will come up with a solution for it as pz wasn't built with many screen resolutions or free choice of font sizes in mind. this would have been easily doable if the definition of font sizes itself would not change so "small" becomes a wholly different font.



UI:
- moved the "options" button to the top bar for those who can't reach the bottom one due to screen size / font size interaction
- when clicking "save and close window" the settings are not just saved but immediately applied without having to close and open the ui again
- adjusted the max height for the right column dataview on the "start" tab
- a scrollbar will now appear for the available tabs on the "start" tab

BTSE_Economy:
- renamed sandbox var "Allow exchange of valuables to currency" to "Allow exchange of valuables to currency anywhere" because with the UI being available people have access to the valuables exchange function everywhere, not just in bank areas or at an ATM. option tooltip shows info now.
- renamed sandbox var "Allow valuables exchange at ATMs" to "Allow valuables exchange at any ATM". if this is checked and the "anywhere" option isn't, players need to be at an ATM to exchange goods. option tooltip shows info now.
- if none of the above mentioned sandbox vars is checked then you need to set an ATM up via firmware update to allow valuables exchange
- added 10 more vehicle thumbnails, again courtesy of Appendiburst

This update contains 356 modified and new files compared to the last BTSE release. Its main feature is the new UI that is shared between users and staff members. Restrictions are built in from the start so do not freak out or panic because you think you are seeing an admin tool. You are supposed to see it as user too - if there are things you are allowed to see, that is. This first version contains more than 21 modules that get added depending on which submods you choose. The focus of this update was to create UI for "BTSE_Blueprints", "BTSE_Economy" and "BTSE_Tools" as those were the most context menu heavy submods. I also added a lot of things and fixes on top (see below). The UI has settings for scaling and transparency. Click the button on the bottom right.

Some UI screenshots[imgur.com]

Thank you Appendiburst for creating the vehicle thumbnails and once again thanks to KI5 for all the tile work, icons, as well as the design brainstorming. Thank you to the ones who went through the trouble of providing translations in the appropriate discussion section. I know it is a ton of text to translate so I appreciate it very much! Thanks go out to the Project Apocalypse, A Path Above, Dawn of the Dead and Z's fun servers communities for testing.

Last but not least thank you to all the people in those discords out there saying this mod is shit because it has no UI. I wanted to play it safe with UI for the time being because I drank the "We're doing a UI framework overhaul soon" Kool-Aid a long time ago but your dismissive and depreciating comments drove me to finally get it over with.

Global:
- copious amounts of necessary code changes and restructuring. everything was tested for a long time but there could be some broken eggs
- changed all occurrences of "ipairs" to a custom iterator
- added sandbox var category ""BTSE | UI"" with checkboxes to allow / forbid ui being offered on right click. reverts some options to context menu based interactions

BTSE_Base:
- added modular UI framework (currently tabs, player tools and gadgets) with component factory and lots of custom components. made some things nicer, some more easily usable, added buffered renderers - just happy little trees all around.
- added another error check for buffered "OnSquareLoad" handlers. if you're still plagued by them, try setting the sandbox option "BTSE | Core" > "Buffer square load events" to "0"
- migrated sandbox option ""Use RPName (first / last name) instead of usernames where possible"" from "BTSE_Chat" here
- migrated sandbox option ""Try to replace usernames with RPNames in player:Say calls"" from "BTSE_Chat" here
- added spanish translation courtesy of Castorcillo

BTSE_Blueprints:
- added UI
- added option to maybe make things unbreakable on paste

BTSE_Chat:
- removed some sandbox options, see "BTSE_Base"
- moved code files from "client/CommandHelpers" to "client/Helpers/Chat"
- reworked tandy suffix logic. you can set "allowTandySuffix" when registering the command. when commands are in group ""chat"" or ""radio"" and are behind staff rank the suffix will be disabled, or enabled when they have a range defined. commands have been adjusted accordingly
- using the radio channel context menu above the chat window will now respect the settings for announcing join/leave of channels

BTSE_Economy:
- added about 60 new shop thumbnails for KI5 vehicles courtesy of Appendiburst
- added new shop terminal tiles with 3 different overlays governing what the shop offers (item / vehicle / both). the old vending machine and area bound global shops should still work but the terminals are nicer and not a kludge like it currently is
- implemented methods to add things to the shop and valuables pool with error checks for the given values as a future proof way of doing things. you should migrate to this way of adding shop entries as soon as possible (see "BTSE_Examples!"). errors encountered by these functions are logged to "btse_economy/shop_errors.log"
- added a UI gadget to dump the existing economy configuration in the new format for updating the server's "ValuesAndPrices.lua" in your config mod
- shop entries are precached on game boot but that might change to "when first viewed" down the line
- added / reworked logic for finding economy sprites around the player
- existing setups should be unaffected by the changes to sprite detection, the introduction of shop terminals and the changed structure of `ValuesAndPrices.lua`
- added UI components for the following:
- view / manage money
- view / exchange valuables
- item / vehicle shop
- firmware update for atm / vending machine / shop terminal
- vending machine sale callbacks (server says "this was bought") are now logged so you can see which items has been moved to player inventories on the client side
- added a server side fallback to sending a copy of the account balance infos to users involved in a transaction which should help in packet loss situations
- moved code files from "client/CommandHelpers" to "client/Helpers/Economy"
- added new hooks for the shop vehicle spawn process: "beforeBTSEAddVehicle" and "afterBTSEAddVehicle"

BTSE_Examples:
- the file "lua/shared/ValuesAndPrices.lua" now contains the new way of adding shop items with comments. the old way is in "ValuesAndPrices_OLD.txt" don't use both at the same time and whichever you choose, name it "ValuesAndPrices.lua"

BTSE_TileProtect:
- fixed an issue with sledge destruction after breaking whitelisted tiles

BTSE_Tools:
- added a new sandbox option to make vehicles on screen outside of the vision cone appear in the chosen opacity, even if the vehicle is behind them. think of it like the player character receiving object permanence courses during the younger years of their life.
- added a tilepicker as an alternative to the vanilla brush tool. this tool has certain advantages over it, including being able to see ALL (even empty) loaded tilepacks as well as support for tilepacks with gaps
- added UI components for the following existing functionalities:
- manage safehouses by time of last login
- backup / restore of safehouses / factions
- dump current player list
- heal players
- removed "BTSE_Chat" requirement and added UI for the following admin functions:
- prune vehicles by condition, added exclusion of AVCS claims
- prune zpop, added option to exclude player zombies and stopping capabilities
- toggle water and power server wide
- batch change lightbulbs
- catch and release players
- spread leaflets around prefab houses
- item list dump on death to be viewed and restored by staff
- item dump storage within "btse_death_restore" is now in folders by username
- re-introduced the sandbox option to hide the scoreboard from users which inexplicably vanished since its introduction 2024-04-23
- if "BTSE_Chat" is not active there shouldn't be errors restoring / backing up things anymore. errors that nobody reported, of course. whoops!
- moved code files from "client/CommandHelpers" to "client/Tools"

BTSE_Base:
- PARP:waitAndDoASAP() now does things more asap
- some more timer queue performance optimizations
- possibly fixed an issue with PARP:eachInCollection() throwing an error when a collection is unloaded by the game during execution of the loop

BTSE_Blueprints:
- added a sandbox option for the time in ms between queue batches (default = 50)
- added a sandbox option for the amount of tasks done each queue batch (default = 3)

shout out to all the clout chasers and the ones using this to manage their servers without managing to give a simple "thank you" back in the comments! ❤️

BTSE_Base:
- (hopefully) fixed that some objects weren't unbreakable when the player just loaded into the world vs. when the object got into the reality bubble. this affects special containers, mostly.
- added a helper to load script files (recipes, items and so on) via lua directly from inside anywhere in a mod folder instead of having the game load them all on startup. this is useful if for example some recipes depend on another mod or an option to be enabled.
- added an iso flag section to the debug & moddata section of the btse menu that shows sprite iso flags per object
- if a sprite object has the moddata entry "indestructible" set to true during square load it should become indestructible for players
- the timer queue now keeps track of the total sum of remaining tasks without counting every time. if the queue should get stuck regardless, there is a fallback every 10 ingame minutes that refreshes the item count.
- adjusted the square processing function that is involved with the eachObjectOnSquareLoad hook to account for square desync while objects still exist
- added a few more fallbacks for invalid sprite names when logging movable actions
- the sprite moddata and iso flags menu is now available to everyone who sees the btse context menu

BTSE_Economy:
- the ATM firmware update context menu is not restricted to being close to the ATM anymore

BTSE_Examples:
- rewrote the comments in ValuesAndPrices.lua

BTSE_Farming:
- added a few checks for the DrawTextCentre hook so calls of this method with unusual parameter order / count should not lead to errors anymore

BTSE_LegacySecExp:
- added a new sandbox option to limit bag-in-bag container depth. 0 (default) is off.

BTSE_TileProtect:
- added an additional check for sledge yoinking when the sprite name was invalid

BTSE_Base:
- multiple changes to internal file handling methods
- added another check to prevent errors when using `PARP:getObjectSpriteName()`
- added sandbox option to have tile protection (regular movable actions) apply to containers marked as vending machine, dropbox or readonly
- added new hook `"eachObjectOnSquareLoad"` which is called for each object on a square when the square is loaded. parameters are `object`, `square` and `moddata`. the added functions can be buffered a set time (sandbox option) after square load and only executed if the square still exists
- added new sandbox option to set the above mentioned timer in seconds (off by default)
- added new sandbox option to use revised file paths. BTSE grew a lot and this rewrites paths to organize files differently in the `Zomboid/Lua` directory. **ONLY ENABLE THIS ON FRESH WIPES AS IT WILL CAUSE ISSUES IN EXISTING GAMES!**
- changed `PARP:waitUntil` to use a common timer queue for vastly improved performance

BTSE_Chat:
- user mutes are now only appended a maximum of one time to the mute files, regardless of how often the same user is muted by different people
- added a server configurable text replacement list (see example submod under lua/shared/TextReplacements.lua) so if you run an rp server and don't want all that "skibidi lol rizz" you can add replacement texts for those. the feature, if it has server configured presets or the creation of custom replacements by users is turned on, will create a "text replacements" button in the titlebar of the chat window where all replacements can be seen easily. only user made ones can be changed and the server configured ones will always apply and can't be overridden. auto mutes apply to the result of the message. custom text replacements are saved according to server ip so you can have multiple profiles for multiple servers. logs about user set replacements and replaced texts are stored on the server under `Lua/btse_chat/`
- added sandbox option to enable text replacements for users (disabled by default)

BTSE_Economy:
- changed the tile definitions so `"Vending_Vending_Type4"` does not become 4 times the freezers every time one segment is found by the power calculations formula that does not look for the **last** occurrence of a number but uses **ALL** the numbers in a movable name, which is also broken because server side lua can't get any translated texts for modded content anymore. the freezers should not consume as much fuel as a small country when placed down anymore
- adjusted translation key for the fridge vending machine in EN/PTBR/RU
- on square load, containers marked as vending machines should be set unbreakable regardless of the original tile properties

BTSE_Legacy_SecExp:
- added new sandbox option to prevent "Rip Clothes" from being favorited in the vanilla and craft helper UI. related bug: https://theindiestone.com/forums/index.php?/topic/69331-favoriting-the-rip-clothing-recipe-if-you-have-too-many-clothing-mods-can-corrupt-your-character-data/

BTSE_Locks:
- added sandbox option to change the way wall objects are placed to reflect their original sprite properties more and prevent other mods that influence ISWoodenWall to fiddle with keypad walls which has resulted in weird iso flags being applied in the past
- security wall creation / destruction is now staggered to not raise false alarms with log monitoring tools due to many sprites being added / removed at the same time. the time in irl seconds can be set in the sandbox options
- corrected the file names of the RU translations as they were named "EN". sorry!
- moved LoadGridsquare event content over to "eachObjectOnSquareLoad" hook

BTSE_Tools:
- added staff container context menu option to make a container readonly. readonly container contents can only be managed by staff rank.
- added clarification texts in staff container context menus about enabled options (vending machine mode, dropbox, readonly)