I know that most of BTSE is on a certain "find out yourself" basis and I am sad that it is like that but documenting my work in a way that satisfies everyone has become too much of a strain for me.

When I create settings I try to name them well or give them appropriate tooltips with explanation but I know that do not always succeed. I am at a point in my life where I need to decide if I either spend my time documenting every nook and cranny of my existing work or I could instead do what I set out to do in the first place when I began modding, which is to bring some order into my loud head by modding things and sharing them with the world.

My hope is that the ones who were brave enough to explore what this offers on their own and who were able to make sense of all the comments within BTSE_Examples and various other "readme" or "howto" named files in the code help others on their journey.

I am not good at describing things, I am worse at answering comments and I am just trying to at least create something for those who appreciate what I do.

Please don't be mad about the documentation. I'm trying my best and I know it isn't good enough so I hope at least the functionalities this mod offers are.

---

If you like the mod and want to help me, please don't forget to give it a thumbs up. Also please consider donating a burger[ko-fi.com]. It would mean a lot to me.

https://ko-fi.com/bknht

A reminder: for the whole mod to work, BTSE_Base is required to be loaded before the rest. It is assumed to be the case here.

When I write "create a new empty mod" I assume you are starting from scratch, making an unlisted mod for your own server that uses and requires BTSE. If you already have some mod with adjustments, assets and so on running on your server that will do fine as host body.

If you are creating a new mod to hold the prices, kits, pictures or changed translations and so on, don't forget to make it unlisted so it does not clog up the workshop like the usual suspects.

These tutorials show how to customize features and content within BTSE so you do not have to modify, reupload and/or distribute the mod. I explicitly do not allow reuploading my stuff, especially if somebody did not read the instructions (or the mod page for that matter).

Urgently check this if you want to:

• Implement custom payment functions or currencies
  
• Add a proper translation for a custom currency
  
• Set prices for the ingame shop (global item / vehicle shops)
  
• Set goods exchange values (cash for loot at the bank / ATM)
  
• Create commands
  
• Configure available starter kits and their contents
  
• Configure server wide text replacements
  
• Add new crops
  
• Leverage multiple methods of tile protection

---

This mod contains a mix of various code examples that do not play nice with a live server because they introduce nonsensical things meant to be examples. If you redistribute this mod instead of taking / modifying the files you are being told in the other guides then you will have issues, including mod id mismatch conflicts.

Copy and paste areas of the map, even between servers and game modes, as long as the tilepacks are available. Has a blueprint library feature and you can share blueprints as Base64 string like in Factorio.

---

---

The player has an area around them that is actively held in the RAM. This area is around 150 tiles in diameter. Everything outside of it does not exist anymore so if you are trying to copy and / or paste areas that are outside of that scope it will not be properly done.

It is generally best to split large areas into multiple blueprints and keep the player in the middle of the area during operations. To create a Blueprint folder, just name the blueprint "My folder name - The name of the blueprint part"

---

• Tiles, including grass, trees and other sprites.
  
• Moddata stored within a tile

• Container tile contents to not bloat the ini file too much.
  
• Building and / or room definitions. Lots of prebaked houses have no proper "roof" and instead rely on room definitions to mark the space as enclosed. The room definition not being copied will be noticeable when copying these houses. Player construction is a-OK.
  
• Water tiles. These will be replaced by sand because during testing water sprites could sometimes break the chunk leading to it being reverted.
  
• Tile properties that differ from the tile pack. If you have a building tool that explicitly sets things unbreakable for example, even if the tile itself says it is breakable, it will adhere to the rules of the tile definition.

---

• The blueprints are stored locally in your Zomboid Userdata folder, Lua, "btse_blueprints".
  
• You can copy and paste between savegames, game modes, servers (as long as you have the rights to do so). The only limitation is enabled tile packs. If one is missing it will point that out in the blueprint selection.
  
• I can't stress this enough: DO NOT select the text when pasting a blueprint string. The game will go into meltdown because of the text highlighting.
  
• By default the tool is available to admin rank only. To change that, use the sandbox variable for the blueprint tool whitelist. Everybody with staff rank can be enabled to use it and this list will be used instead of the admin rank.

This submod is the foundation of a custom command module. Do not use this with other chat mods like the Chat bubble one or these "join/leave" things. It is supposed to be used standalone. In short it contains:

• Full chat system overhaul. Radio text channels in tabs, faction chat tab and more. No /whisper, no /all chat.
  
• (optional) Role playing chat features galore
  
• Comprehensive logging
  
• Starter kits you can define and that can be turned in once per user

Available commands can be checked by checking the commands guide on top of the chat window. The available commands depend on the access level of the user. This mod still uses the vanilla chat methods under the hood and therefore is subject to their flaws (specifically logging) too.

---

Required mod in the mod line: BTSE_Chat

• create a new empty mod (or reuse your server adjustments mod)
  
• open the folder for BTSE_Examples and copy
  lua/shared/StarterKits.lua
  to your new mod under the same path
  
• open the copied lua file and follow the comments in it
  
• upload your mod containing the copied starter kit list to the workshop
  
• load the mod containing it after BTSE_Chat

If you modify this file locally and want to "test" the starter kits, keep in mind that the server validates the info in this list and does the spawning. This is so it can't be modified on the client side for an attacker to gain an advantage. If the server is not aware of your changes you will not receive the correct items and/or the kit will not be known.

---

Remove, on the server, the folder

---

Required mod in the mod line: BTSE_Chat

• create a new empty mod (or reuse your server adjustments mod)
  
• put the image you want (which should ideally be smaller, better wide than tall) into a folder there. I would suggest using "ui" as folder.
  
• upload / update the mod carrying the file
  
• open the sandbox settings on your server, go to the chat settings
  
• add the path to the sandbox setting for the welcome image. The path is not absolute and should be entered like this: media/ui/your_image.png

---

Required mod in the mod line: BTSE_Chat

First, as before, you need to create a new empty mod (or reuse your server adjustments mod) and load it after BTSE_Chat.

Depending on what you want to do there is an easy way and 2 brutal ones.

Method 1 (overriding translations - preferred safest way)

Create a translation file in your mod (media\lua\shared\Translate\EN\IG_UI_EN.txt) and override these strings to your liking. The string does not need to contain both placeholders.
%1 is the username (or rpname depending on sandbox settings)
%2 is the message


Sandbox option "simpler formatting" uses these:


Method 2: redeclaring the command, not recommended

If for some reason the solution above was not sufficient you can redeclare commands just by naming them the same way existing ones are named. See the commands example in BTSE_Examples.

Method 3: copying and overriding the commands files

This is the most oafish method. Override the files you want within BTSE_Chat\media\lua\client\CustomCommands

---

Items done by KI5

• Banking system like in the olden days - area locked by sandbox options and / or with custom ATM tiles. Includes fees, taxes, interest and more.
  
• Player stocked vending machines, integrated into the currency system
  
• Integrated global shop for vehicles and items, bought and spawned by the users themselves
  
• Shop terminal tiles with different overlays
  
• Does not rely on items being used to purchase or share money. This means it can't be duped.
  
• Transactions are server validated

---

Required mod in the mod line: BTSE_Economy

• create a new empty mod (or reuse your server adjustments mod)
  
• open the folder for BTSE_Examples and copy
  lua/shared/ValuesAndPrices.lua
  to your new mod under the same path
  
• open the copied lua file and follow the comments in it
  
• upload your mod containing the copied and adjusted price list to the workshop
  
• load the mod containing it after BTSE_Economy

If you modify this file locally and want to "test" the prices and items, keep in mind that the server validates transactions when you try to buy something. This is so it can't be modified on the client side for an attacker to gain an advantage. If the server is not aware of your changes the transactions will fail.

---

You can do this in the same mod you used already, or your server adjustments mod.

The pictures are expected to be under any of these paths. First hit wins:

You should use the BTSE UI -> Gadgets -> Take vehicle shop screenshots gadget but if you want to do it manually, you can do so, too.

During updates vehicle pictures of vanilla cars and at the KI5 vehicle collection will be included.

---

Tiles and items done by KI5

Does not add any crops, but it adds tons of error handling and checks for the vanilla farming system. Allows you to remove farming mods safely and you can add crops very easily from within your own server mod. Do not redistribute the contents of this (use this as requirement and load it before you add your own crops) and check BTSE_Examples for an easy showcase and detailed descriptions on how to add your own stuff.
This does the same as my old "Just tomatoes" mod and more. Enable this one - even empty - and you're protected during the removal of farming mods which would otherwise be breaking the server.
Just like it is usually with farming: do not expect this to get along with other farming mods. It was and is meant to replace those with an inhouse mod specific to servers. The only exception that will 100% work is More Smokes.

---

Contains various helpful options to combat exploits and and the anti cheat stuff (which is not maintained anymore) that was formerly within BTSE_Tools. Do not expect all of it to work against modified clients.

Do not rely on this to secure your server. Look for alternatives that are actively maintained.

Adds keypad lock functionality (password protection) to doors. Keypads can be crafted or installed for free by staff members.

---

What IS a keypad lock?

A keypad lock is an item you can use to attach a code lock to a door or gate. The keypad is then just a bit of data taking care of locking and unlocking the door/gate it is attached to. A keypad is a functionality attached to a door.


What ISN'T a keypad lock?

The walls it places down, the gate or door


What are the walls for?

PZ desyncs moddata and/or door open state. The walls add another layer of protection so it is wise to enable the option


My garage door has some elements up, some down and it is all that damn keypad's fault

This issue happens even in vanilla single player games, so... hard pass on that. Inform yourself before accusing a mod for a core game issue.


The door is broken because the keypad is bugged

If the door you attached the keypad to has no tile properties for being indestructible, it can be destroyed by zombies or players (exception: see below).


What does the option for indestructible keypad related tiles do?

It makes the gate / door and the walls placed through the keypad locking process indestructible.


Why does this not work in tandem with vanilla door keys?

Because one of the mechanics it uses as a redundant way of locking is a vanilla door key id. Vanilla door keys and keypad locked doors are not supposed to coexist. It even generates the Key ID outside of vanilla key bounds to make sure. Imagine putting up a keypad lock only for somebody with a key to bypass it. Use the "unlock door" option like it is intended or don't use a keypad lock on that door.


I can still use "E" and other vanilla key bindings / actions to open a door

Yes, that happens and can't be reliably prevented. That is why there is an option to put up a tile wall as yet another redundancy layer.

---

Items done by KI5

A server side implementation (as far as this game permits) of a character save and restore mod with the twist that you can not only use the regular restore tokens but also a pod tile based system depending on what your server wants.

---

My goal with this was to implement a character restore solution that does not rely on local info or can be modified by users and with my "server truth" approach this ended up becoming a system that dumps all kinds of character info to the server when people die or during snapshots. When a restore is requested, the server will send individual packets to the client until it is all done. The sandbox vars being used to determine the restore parameters are also only read on the server and carried through the running restore process to prevent people with broken sandbox settings from getting different results. The items being used to initiate restore processes contain data about the dump but only the token ID is relevant as I do not want to trust a local item to be the authority on what is being restored. I've desync proofed things as best as I could and think I came to a stable result. The files on the server are kept in folders organized by username and named by their contents and the timestamp of the player's demise. There is a setting to change how many versions of each user's characters are kept (10 by default) and the old files on the server will be emptied out (I have not found a way to delete files so 0KB is all I can do for now). Because each dump contains all the info this mod is able to restore this means that if you change your mind about a setting later on, this setting will apply to all restore processes, old and new dump, the same way. If you for example decide to change the skill loss percentage it will always be applied for old and new dumps.

---

I got inspired about this because I was reading about MKULTRA, specifically the Montreal experiments, with sensory deprivation tanks, changing memories and other wonky stuff. The system itself can be used as a two-parter, depending on what kind of server you want to run. The imagined gameplay loop during development was that people die, then respawn, "find" a token in their pocket and can get a low amount of their old self back, then travel to an admin set up pod location (which are marked on the map automatically as they are discovered if you want) to get the main stuff back. You can configure the mod to work fully without pods (just from the item) and you can configure it to require pods for restores at all times. Do what you want, the options are there. There is no need to refresh or write down info somewhere, it is all automated for the convenience of the user.

---

The rules for restoring tokens are simple:

• A player can restore one dump ID (the name of the dump) per lifetime. Once a restore is done they are locked into it until they die again.
  
• A player can restore the same token during this lifetime as often as they like (in case of disconnect or crash). If someone's restore process was interrupted they can retry the same token again.
  
• If a player chose the wrong one (this sign won't stop me because I can't read!) they can just kill their character and pull the right token from a pod or their stash.
  
• Each character dump is unique. There is no "best" version. You can build hop as long as the token isn't too old (deleted) and the sandbox settings allow this. If someone dies with a shell of a char and restores the data of course they will be empty again. Find the right token and restore that one.
  
• If you want to start a "new build" then do not restore the old token, if it is configured to restore professions, traits and so on. Just start fresh.

---

It is HIGHLY advised to "trait lock" characters as it prevents people from exploiting XP gained by OP traits, dying, then taking new OP ones and then becoming gods in a short time. This is also a must-have if you have mods that add or remove traits, like dynamic traits, SOTO or others. If you do not restore traits you can't expect them to magically appear again after dying.

Most important of all: do not expect all options to get along perfectly and work out the way you think they do when you disable certain ones. The more things you restore, the better the result.

---

This mod comes with options to restrict the clothes selection on the spawn menu. This means you can run the "All Clothes Unlocked" vanilla sandbox var and whittle it down to what you want people to be able to spawn with. If you want insight into the thought process to see what is being removed and why, get into debug mode and when on the spawn screen check the local "Userdata/Zomboid/Lua/parp_debug.log" or depending on if you have the "New" file name option checked in the sandbox, "btse_debug.log" file.

---

Snapshots:

When using trait mods there is often an issue with people being asked to create a new character and if they go through with it, the server side character is deleted. To make this sting a bit less I've added an automatic backup being done without dying, called "Snapshots" which will at least keep the skill loss at a minimum. By default players will create a snapshot every 24 ingame hours (so about 1-2 irl hours on most servers) and if they did delete their character by making a new one they will get the consolation snapshot in their pockets instead of a regular dump file. Sometimes desynced player moddata can lead to a snapshot being delivered too but it is rare and hard to reproduce so just use your best judgment.

Protected XP:

A fresh character spawns with traits and XP which are immediately saved to their moddata and internally handled as protected XP. When they die this data is added to their character dump. If skill loss is calculated these values always remain intact as a bottom line. If you restore a dump those values are restored too, so they carry over. The protected XP is linked to restoring the profession. If the profession of the dump to restore matches the current profession of the character OR profession restore is allowed the protected XP will be applied.

The mod comes with a Player tool in the UI that allows you to view each Player's dump info, send them Tokens or push full Restores. You can place Pods by using the BTSE "Place Movable" context menu. Placed Pods can be configured via context menu to show the number 0-99 and there are some Graffiti sprites you can enable via Sandbox option. Probably not your cup of tea because those were added as thank you to some nice people that supported me over the years and those references are probably confusing. If you run Events, have Skill loss enabled and do not want people to lose their Skills, set up a Pod as an "Event Pod" on site which will always 100% restore them. You can configure an amount of free Downloads for Tokens which will allow people to visit a Pod and pull out any of their available Character dumps as a Token.

---

Item based and pod based restore options are configured separately and each page has a range of options you can choose. Options range from percentage based loss to exclusions and custom percentages per skill as well as all the things listed below. There are also shared settings which have their own settings page. Default works best, as usual.
Every time a player dies or in configured intervals a dump is stored on the server (snapshots, see below). Each dump contains the following:

• Skills (as long as it is within the PZ skill system), the total XP in it and the level as value
  
• Traits
  
• Recipes
  
• Profession and related multipliers
  
• Book XP multipliers
  
• Read literature
  
• Media lines listened to (to prevent VHS cheese)
  
• Nutritional information (weight, calories, carbohydrates, lipids, proteins - no more dying just because you want to respawn with a full stomach)
  
• Survival info (kills, hours survived)
  
• Character full name
  
• Protected XP (see below)
  
• Crafting favorites except "rip clothing"

---

There is a plugin system that allows clever people (other modders or server staff) to add support for various things to be saved and restored. There is a "HowTo.txt" in "lua/shared/Helpers/SkillRestore/ModSupport" as well as plenty of examples in there. Support (full or rudimentary, depending on what came up during testing) is given for these mods out of the box and will be applied automatically depending on their mod ID being loaded on the server:

• BTSE (known keypad lock codes, chat radio channels and Tandy options)
  
• Simple Overhaul Traits and Occupations (SOTO)
  
• Evolving Traits World (ETW)
  
• Musicians of the Wasteland (MOTW, because it uses moddata instead of skills)
  
• Lifestyle (music tastes because those add traits).

---

If you want to leverage what this mod provides but do not want to have users spawn with tokens, load up any of your server mods, those ones with all adjustments and whatnot, then add this in a file under "lua/shared":

---

Tiles and items done by KI5

Allows for a variety of included options to protect the world from griefing and destructive actions. Allow / forbid pickups or destruction of various objects and sprites. Comes with sprite whitelist and blacklist, user whitelist, various predefined container type exclusive pick up options. Includes options to log movable actions.

To have this work properly you need to set these vanilla sandbox options to have the actions policed by the mod, not the game:

It is not only the spiritual successor to ValhallaAegis' container protection, it is vastly improved. If you use this submod, disable the container protection in ValhallaAegis.

Contains mostly admin tools, logging and specialized commands as well as lots of QOL things to adjust your server environment.

This is a hodgepodge of an enormous amount of seemingly random tools that might come in handy or not. The mod is a place for everything that does not explicitly fit in with the other existing submods.

It's a lot and I always randomly add one or two things so trying to describe it and most of all keeping it current is impossible for me. Keep an eye on the change logs and load this into a coop save to inspect the options yourself.

---

Required mod: BTSE_Tools

You can define *zones* not houses or other things, which is why i write in xy pairs of 1,2,3,4 for a total of 2 declared zones. A zone has 2 orientation points drawing a rectangle. The format is explained as follows:


Point 1 is x1,y1 - let's say top middle of the rectangle
-> then a colon, think of it like saying "until"
Point 2 is x2,y2 - the bottom middle of the rectangle

You draw an imaginary line between those points and you have the "not claimable" zone within the rectangle area.

Then you can list another zone delimited by a semicolon:
Point 3 is x3,y3, colon, point 4 is x4,y4

You can list as many of these rectangles as you want.

Proper usage would look like this, to exclude a large area and 3 smaller ones:

• server authoritative for the parts that reasonably can be done so: claiming, releasing, permissions, theft (see further down), logs
  
• extensive logging on a per-vehicle basis on the server that staff can access
  
• does not use global moddata for storage of claims and permissions (less prone to desync and less packet spam)
  
• (option) set the amount of allowed vehicle claims per user
  
• multi tiered highly detailed permissions system:
  
  • special permissions for 3 groups: everyone, faction and safehouse
    
  • add individual users to the permissions
    
  • permissions sum up to a grand total and complement each other
    
  • deeper hooks into various parts of the game to police more things than any other vehicle ownership mod does
    
  • permission presets for groups
• claim and release vehicles within your reality bubble either from the vehicle, or from the UI
  
• (option) claiming requires and consumes vehicle papers you can find in the world or add to the starter kit of the server. this combats the usual "run around, claim valuable vehicles and never log back in" crowd.
  
• abandon vehicles that are not in your bubble. in case it is in someone else's it will be unclaimed immediately, if not it will be up for a user to freely unclaim it.
  
• (option) vehicle claims expire based on when the owner was last seen online. users can check if a vehicle is available for this.
  
• (option) claimed vehicle theft - highly configurable:
  
  • (option) requires and consumes a slim jim item (doubles as a weapon) that you can find in the world
    
  • (option) factors in the thief's traits and skill levels
    
  • generates a chance to trigger a vehicle alarm and a success chance dynamically
    
  • (option) if the owner is online they are informed about the theft happening, stopping and, if the theft was successful, that their car has been stolen
    
  • anyone can try stealing but they most likely end up ringing the dinner bell instead. gives skills and traits choice more meaning.
    
  • (option) grace period before rolling for chances begins. this is the minimum length of a stealing action.
    
  • (option) theft protection for a chosen amount of minutes after the owner logged out. this is in case someone disconnects or gets kicked which could cost them their vehicle.
    
  • if the thief does not have a free slot the theft is unsuccessful. if it was successful, they become the new owner.
• multi tiered "abandoned vehicle check" functionality anyone can do where a chain of decisions is evaluated based on server settings and a solution presented:
  
  • last login time of the owner
    
  • was the car abandoned?
    
  • is stealing allowed?
    
  • if so: is the vehicle logout protected still?
    
  • if nothing applies a message is shown that the vehicle is not abandoned
• migration friendly: does not interfere with other vehicle ownership mods, can run in parallel. if a vehicle is detected to be managed by avcs or valhalla, no protections for BTSE will be evaluated and claiming will not be offered. gives servers time to have users unclaim in the other system and reclaim in the new one.
  
• lots of options on top that i probably forgot!

---

Keep in mind these mechanics can be turned on / off and be customized at any time. The video was made by @TheSonOfMogh on Project Apocalypse to showcase the way they configured it.

---

Adds new hooks:


Examples / setup here:
and
Which checkboxes are under permissions?

Default permissions?

Other mods can register a vehicle action as action that deletes a vehicle via
which will prevent the action automatically, if the vehicle is claimed

---

Tiles and items done by KI5