Skip to content

HOME

Jump to bottom
theblackswitch edited this page Feb 11, 2026 · 13 revisions

Welcome to the switch-lib documentation. Here you can find short references and examples on how to interact with the features of my datapack and information about the workflow and design of this library.

Note

In this wiki, everything between <> needs to be replaced with an appropriate value.

🖥️Installation

To combine this library with your datapack, just unzip the release and move the theblackswitch namespace into your datapack. Next add #theblackswitch:load to your Minecraft load-tag and boom, you're done :)

✨Using the features

For performance reasons not all features (especially ticking ones) are enabled by default. You can enable them by running #theblackswitch:<version>/<feature>/enable or by running one of the functions added by this feature (if applicable).

📎Vscode snippets:

I've added vscode snippets for almost all the features so you can, for example, easily import a motion check predicate in your code. You'll find them in the .vscode folder in this repo. switch_lib_user.code-snippets is intended for library users, and switch_lib_dev.code-snippets is intended for developing the library itself. To apply them to your vscode workspace, make a .vscode folder in your root workspace folder and place the snippets file in there. Now you can use them; just start typing the feature you want, and it will auto-suggest command lines to import.

🏷️Versioning:

The datapack uses semantic versioning: major.minor.patch:

  • The major increases for every complete rewrite or big changes that require attention
  • The minor increases for breaking changes that are not backwards compatible. This number also increases when big features are added.
  • The patch increases for bug fixes or optimizations that are backwards compatable. Some smaller features may increase this number instead.

Note

The changelog can be found here

When multiple datapacks include this library, they can all depend on different versions of the datapack or start overriding each other. To solve this, the datapack uses a custom version resolution inspired by lantern load's version resolution. It first loads each major.minor version separately without interference (even internal tags and scores have a different namespace). Within these versions, the datapack automatically loads the latest patch version it can find; this way, it's as stable/optimized as it can be without causing compatibility issues.

Due to each file being moved to a versioned folder, the location of each file will change every time this library updates. This can get very annoying when updating the library version of a big datapack since you now have to go through each file and change all references to the library. To solve this problem, I've written a plugin for the pre-compiler beet Documentation about the plugin can be found here

PS: If you don't know what beet is, you should definitely check it out, it's very cool!.

📄Documentation:

🪲Debugging

If you need some debug info, you can add the tag tbs.debug to yourself. This will log all debug to your chat once you've reloaded.

When the datapack loads, it will check if there is a player online with said tag and set the #tbs-<version>.debug_enabled score for the objective #tbs.server_data to 1. That way we can optimize our debug checks to only a single score instead of a full-on player selector when we're not using debug features.

🤝Contributing

If you're missing some features or you just want to help improve this library, feel free to contribute!

Precompiling

This library is written using the precompiler beet together with its extensions bolt and mecha. This allows for faster and more reliable coding whilst keeping everything clean and optimized.

To address the versioning issues, I've written a beet plugin that automatically applies version resolution to the code. For documentation about this plugin, you can take a look here

Guidelines

You should follow these guidelines as much as possible:

  1. It's best to use the dev branch for development
  2. A feature that includes a tick function should be disabled by default and have an enable function.
  3. Use smithed's datapack conventions (eg. namespacing).
  4. Follow the version resolution for maximum compatibility.
  5. Optimize as much as possible. We use plain mcfunction files and not .bolt files (also the version resolution won't work with bolt files)
  6. When passing arguments to functions, prefer using storages instead of macros.
  7. Seporate each feature in an organized folder structure.
  8. Use function tags as an interface for the user; this will also be needed for valid version resolution.
  9. Tags should never override eachother
  10. All tag values should have required set to false
  11. You can (but don't have to) add some debug logging messages. If you do so, please follow the conventions explained in the debug section.
  12. Document your feature please :)
  13. Create vscode snippets for each feature.

Writing Debug

Sometimes you want to add some debugging messages that your users can enable. To use the same system as explained in the debug section

You just have to check for the score #tbs-<version>.debug_enabled tbs.server_data. This can get clunky very fast, so I wrote another small plugin that makes this cleaner. You can find the documentation here

👍 Check my other stuff.

If you find this library useful, maybe check out my other projects or give me a small donation.

Clone this wiki locally