Skip to content
pop4959 edited this page Sep 7, 2024 · 69 revisions

Wiki

Development Builds: CodeMC or Github Actions

Why Bolt?

LWC has been the go-to protection plugin for a long time. It's a classic. Unfortunately though, due to its age and the complexity of the code, as well as some of the design decisions made early on in its development, it's difficult to update and support new modern features.

Because of this, I decided to start working on Bolt, which is intended to be a complete replacement for LWC.

Bolt currently has these advantages over LWC:

  • Completely rewritten database handling: No blocking reads on the server thread. Faster and hopefully safer too.
  • Improved protection matchers: Every block can be protected, not only containers. Scaffolds, nether portals, vines, you name it.
  • A permission system that is much more flexible: Default protection types and permissions as well as access types and permissions can be fully customized.
  • First class entity locking support: Finally you can protect item frames, armor stands, and more. Entities can even be matched with blocks (for example, a locked lead attached to a fence will also cause the fence to be protected to prevent breaking the lead through the fence).
  • Improved handling of many game features: For example, use a redstone protection type wherever you need to protect redstone components. Also, hoppers automatically resolve their permission to take/put items from containers (so if you have a chain of protected hoppers, since you own them all items will transfer through seamlessly - no unnecessary hopper flag).
  • Custom translations with MiniMessage formatting are supported: Yes, finally easy-to-read color codes and named placeholders.
  • And much more: TBH the stuff above is just what I can come up with off the top of my head. Read on to see more in-depth explanations of Bolt's features.

If that hasn't convinced you, don't worry. LWC will still be updated, however most new and interesting development will be focused on Bolt.

Migration for LWC users

Bolt includes conversions between the database formats of Bolt and LWC. If you are currently using LWC, it is incredibly easy to switch to Bolt, and likewise, switch back to LWC if things aren't working the way you expect.

The conversion should be safe, but be responsible and make a backup of your database(s) before continuing in case anything happens.

Please note:

  • If you used the LWC Trust add-on, this data will be automatically migrated when installing.
  • If you had protectable blocks that aren't in the default config, these will automatically be copied over to Bolt's config when installing.
  • If you had protected entities, converting these may take some time depending on the size of your world. You will be asked to convert these separately.

LWC -> Bolt

  1. Ensure both plugins are installed
  2. Use the command /bolt admin convert lwc to convert your LWC data to Bolt
  3. Uninstall LWC and restart the server
  4. Do not delete your lwc.db file, as it will still be useful if you decide to switch back

Bolt -> LWC

Important: Please let us know by making an issue or posting on the Bolt Discord if you are temporarily uninstalling due to a problem or missing feature. It is a goal to fix any issues preventing you from fully switching to Bolt.

  1. Ensure both plugins are installed
  2. Use the command /bolt admin convert bolt to convert your Bolt data back to LWC
  3. Uninstall Bolt and restart the server
  4. Do not delete your bolt.db file, as it will still be useful if you decide to switch back

Migration for Lockette users

Bolt includes conversions for Lockette, as well as other forks like Deadbolt, LockettePro, and BlockLocker. If you are using one of these plugins, it is incredibly easy to switch to Bolt, and your existing signs will be left in place in case you want to switch back at any point.

The conversion should be safe, but be responsible and make a backup of your world(s) before continuing in case anything happens.

Please note:

  • Unlike the LWC migrations, converting data from Lockette can take a very long time. This is due to the fact that there is no database and Bolt will need to scan the entire world for signs and load those chunks to re-build protection data from scratch for those blocks. Simply leave it alone and it will eventually complete. It should be safe to continue using your server while the migration is taking place.

Lockette -> Bolt

  1. Use one of the following commands to convert your Lockette data to Bolt, depending on which plugin you have:
  • /bolt admin convert lockette
  • /bolt admin convert deadbolt
  • /bolt admin convert lockettepro
  • /bolt admin convert blocklocker
  1. Uninstall Lockette if you have not already and restart the server

Bolt -> Lockette

  1. Re-install Lockette
  2. Place back any signs (if applicable) that were removed after migrating to Bolt

Commands

Player

Lock

Usage: /bolt lock [type] (alias: /lock [type])

Permission: bolt.command.lock

Description: Lock something. Optionally provide a protection type to lock with (defaults to private).

Unlock

Usage: /bolt unlock (alias: /unlock)

Permission: bolt.command.unlock

Description: Unlock something.

Edit

Usage: /bolt edit (add|remove) <player>

Permission: bolt.command.edit

Description: Edit a protection to add or remove a player's access.

Modify

Usage: /bolt modify (add|remove) <access> <source-type> <sources...>

Permission: bolt.command.modify

Description: Add or remove sources with given access to a protection's access list (ACL).

There are a few notable built-in access source types:

  • player for players
  • password for passwords entered with /bolt password
  • permission for permission nodes
  • group for groups managed by /bolt group

Group

Usage: /bolt group (create|delete|add|remove|list) <group> [players...]

Permission: bolt.command.group

Description: Manage custom player groups, which can be used in access lists (ACLs).

Trust

Usage: /bolt trust (add|remove) <source-type> <source> [access]

Permission: bolt.command.trust

Description: Prompt, list, or confirm changes to your trust access list.

Transfer

Usage: /bolt transfer <player>

Permission: bolt.command.transfer

Description: Transfer a protection that you own to another player.

Password

Usage: /bolt password <password>

Permission: bolt.command.password

Description: Enter a password for a protection that has a password source added.

Mode

Usage: /bolt mode <mode>

Permission: bolt.command.mode

Description: Toggle a player mode. For example: persist, no lock, no spam.

Help

Usage: /bolt help [command]

Permission: bolt.command.help

Description: Displays help.

Info

Usage: /bolt info

Permission: bolt.command.info

Description: Display protection information.

Admin

Cleanup

Usage: /bolt admin cleanup

Permission: bolt.command.admin.cleanup

Description: Clean up protections from the database that no longer physically exist in the world. This can happen, for example, when removing blocks without breaking them using other plugins such as WorldEdit.

Convert

Usage: /bolt admin convert or /bolt admin convert back

Permission: bolt.command.admin.convert

Description: Convert an existing LWC database to Bolt. See the section above about migrating.

Debug

Usage: /bolt admin debug

Permission: bolt.command.admin.debug

Description: Displays technical protection information.

Expire

Usage: /bolt admin expire <time> (seconds|minutes|hours|days)

Permission: bolt.command.admin.expire

Description: Removes protections that have not been accessed in some time.

Find

Usage: /bolt admin find <player>

Permission: bolt.command.admin.find

Description: Find protections for a given player.

Flush

Usage: /bolt admin flush

Permission: bolt.command.admin.flush

Description: Immediately save all protection changes to the database.

Purge

Usage: /bolt admin purge <player>

Permission: bolt.command.admin.purge

Description: Removes all protections for a given player.

Reload

Usage: /bolt admin reload

Permission: bolt.command.admin.reload

Description: Forces a complete reload of Bolt's configuration, re-loads translations, and updates protection types, access types, and protection matchers.

Report

Usage: /bolt admin report [disable]

Permission: bolt.command.admin.report

Description: Displays technical information regarding protection event triggers and cache hits/misses.

Transfer

Usage: /bolt admin transfer <player> [to]

Permission: bolt.command.admin.transfer

Description: Force transfer a protection to a given player, or all protections from the player to another player.

Permissions

bolt.mod allows the player to access and view contents all protections without the ability to edit or destroy them.

bolt.admin allows the player to bypass the ACL for all protections. Effective ownership over everything.

bolt.permission.<permission> allows the player to bypass a permission on the ACL for all protections.

bolt.protection.notify notifies the player when interacting with a protection.

bolt.protection.notify.self notifies the player when interacting with their own protections.

bolt.type.protection.<type> grants permission to use a protection type (if require-permission: true is set for that type).

bolt.type.source.<type> grants permission to use a source type (if require-permission: true is set for that type).

bolt.type.access.<type> grants permission to use an access type (if require-permission: true is set for that type).

bolt.protection.autoprotect.<type> grants permission to auto protect a protection (if autoProtectPermission: true is set for that protection).

bolt.protection.lock.<type> grants permission to lock a protection (if lockPermission: true is set for that protection).

bolt.command.info.full grants permission to view full info including access list with the info command.

Configuration

Default translation language.

Built-in support currently only for English, however you can create your own custom translation and use that value here.

language: en

Settings

  • use-action-bar: If enabled, action messages to go to your action bar instead of chat.
  • per-player-locale: If enabled, players will receive localized messages, rather than the language set via the language config option, if available.
  • default-modes: A list of player modes which are enabled by default.
settings:
  use-action-bar: false
  per-player-locale: true
  default-modes: []

Database configuration

  • Type is the database type; either sqlite (recommended) or mysql.
  • Path is the path of the database file (SQLite only).
  • Hostname is the host name, and optionally port, to connect to (MySQL only).
  • Database is the database name (MySQL only).
  • Username is the database login username (MySQL only).
  • Password is the database login password (MySQL only).
  • Prefix is the database table prefix.
  • Properties are a list of optional connection properties to set for the connection (MySQL only).
database:
  type: sqlite
  path: plugins/Bolt/bolt.db
  hostname: ""
  database: ""
  username: ""
  password: ""
  prefix: ""
  properties: [ ]

Protection types. You can define your own here or change the permissions that they come with.

There are a few built-in permissions currently:

  • interact allows interaction with a protection
  • open allows opening a container or menu
  • deposit allows putting items into containers
  • withdraw allows taking items from containers
  • mount allows mounting protected entities
  • redstone allows using redstone on a protection
  • edit allows editing a protection's ACL
  • destroy allows destroying (literally, by destroying / killing, or via unlocking) the protection
  • entity_interact allows entities to interact with the protection
  • entity_break_door allows entities to break the door of a protection
protections:
  private:
    require-permission: false
    allows: [ "redstone" ]
  display:
    require-permission: false
    allows: [ "redstone", "interact", "open" ]
  deposit:
    require-permission: false
    allows: [ "redstone", "interact", "open", "deposit" ]
  withdrawal:
    require-permission: false
    allows: [ "redstone", "interact", "open", "withdraw" ]
  public:
    require-permission: false
    allows: [ "redstone", "interact", "open", "deposit", "withdraw", "mount" ]

Access types. Uses the same permissions mentioned above for permission types. The only difference is these are used in a protections ACL. A user's effective permission to the protection are the combination of the protection type's and any additional access they have. For example, no protection type allows users to edit the protection by default, however this can be granted using the admin access type.

access:
  normal:
    require-permission: false
    allows: [ "redstone", "interact", "open", "deposit", "withdraw", "mount" ]
  admin:
    require-permission: true
    allows: [ "redstone", "interact", "open", "deposit", "withdraw", "mount", "edit" ]

Source types. These are targets for access when editing protections.

sources:
  player:
    require-permission: false
  group:
    require-permission: false
  password:
    require-permission: false
  permission:
    require-permission: true

Blocks. This is a list of blocks that are protectable, and if they will be automatically protected to a certain type upon placement.

Refer to Material for valid values here. You can also use block tags, which can be useful for grouping many similar blocks together under one configuration. Tags start with # and must be quoted.

blocks:
  chest:
    autoProtect: private
    lockPermission: false
    autoProtectPermission: false
  '#shulker_boxes':
    autoProtect: private
  ...

Entities. Similar to blocks, this lists any entities that are protectable and their default protection type when spawned.

Refer to EntityType for valid values here. You can also use entity type tags, which can be useful for grouping many similar entities together under one configuration. Tags start with # and must be quoted.

entities:
  armor_stand:
    autoProtect: private
  ...

Doors. This section is not standard and usually appears as a result of upgrading an existing server using LWC where the door features in doors.yml were enabled. It is offered primarily to make switching to Bolt easier for server owners and players expecting their old protections to work exactly as they did before.

Below are the settings as they correspond to their entries in the doors section of the config:

  • open-iron is equivalent to enabled; if players should be able to open locked iron doors bare handed.

  • open-double is equivalent to doubleDoors; if locked double doors should open together.

  • close-after is equivalent to interval; how many seconds after opening door(s) before they automatically close.

  • fix-plugins is an experimental setting which attempts to fix plugin interactions with doors. For example, interacting with double doors or iron doors to open them in WorldGuard regions where the player does not have permission to the region. Keep in mind this may have unintended side effects so exercise caution while using this.

doors:
  open-iron: false
  open-double: false
  close-after: 3

Special entries are also automatically added to the access and sources section of the configuration which are used by the migration tool to provide support for protections which previously had the autoclose flag in LWC. The access type must be named exactly "autoclose" and allows the auto_close permission, and the source must be named exactly "door". Normally, it is recommended not to give players access to the special door source type and instead add the auto_close permission to protection types or access types for which auto closing is desired.

Translations

Built-in

Bolt comes with many translations already included! These are contributed by community members via Crowdin.

Simply edit the language option in the configuration to select any of these pre-included translations.

You can find a list here. Keep in mind not all may be complete! Please contribute if you notice any missing translations.

Custom

Making your own translation is super simple in Bolt. Simply drop a <lang>.properties file into the Bolt plugin folder. Replace <lang> with the name of the language that you want, and make sure that in the configuration you set this to the same value.

Copy the contents of en.properties and customize to your liking!

Messages use MiniMessage formatting. You can test here first to make sure it works (although it won't resolve custom placeholder tags which are added by Bolt).

Keep in mind that custom translations are likely to break between versions. It is your responsibility to keep them updated.

If per-player-locale is enabled in the config settings, players will receive a localized message, rather than the language set via the language config option, unless one does not exist. In this case, you may wish to translate or stylize each language that you want to support.