Backbone: Scripting Engine for Paper

GitHub last commit

Running a Minecraft server can be frustrating when every minor update, bug fix, or new feature requires you to kick all your players and restart the server.

Backbone is a powerful administrative tool designed to completely change how you manage your server. It allows you to add custom features, items, menus, and monsters on the fly—without ever shutting down or restarting your server. Whether you are a server owner trying to create a unique experience or an admin looking to fix things instantly, Backbone gives you the tools to keep your server online and your players happy.

Key Benefits

Backbone takes the heavy lifting out of server customization. Here is what it can do for your community:

Zero-Downtime Updates

The biggest advantage of Backbone is its "hot-reloading" engine. If you find a bug in a custom feature, or want to tweak how much damage a custom sword does, you can update the file and reload it instantly in-game. Your server stays online, and your players won't even notice a hiccup.

Custom Equipment

You no longer need to buy expensive premium plugins to get custom gear. Backbone allows for the creation of unique items with special abilities, custom names, and specific behaviors. You can easily generate and hand these out to players in-game.

Custom Entities

Want to create a custom guard zombie that stands still and looks at players, or a unique boss monster? Backbone lets you inject custom behaviors into Minecraft's default mobs, allowing you to create entirely new challenges for your players.

Interactive GUIs

Creating complex chest menus (like server selectors, shops, or stat pages) is usually a headache. Backbone simplifies this, allowing you to quickly build interactive menus that look great and respond to player clicks instantly.

Visual Effects

Backbone includes a system for generating custom visuals in the world, like glowing boxes around players or custom holograms, making your server stand out visually.

Persistent Player Data

Unlike older plugins where reloading might erase temporary data, Backbone is built to remember important things. If you have a live counter or specific player states running, Backbone safely stores that information even while you update and reload your features.

Getting Started

You do not need to be a professional developer to start benefiting from Backbone.

Requirements

A Minecraft Java Edition Server running version 1.21 or higher.
PlaceholderAPI (Optional, but recommended for text placeholders).

Installation

Download: Grab the latest .jar file from the releases page.
Install: Drag and drop the file into your server's plugins/ folder.
Start: Turn on your server. Backbone will automatically create a scripts/ folder in your main server directory.
Add Features: You can now drop Backbone script files (.bb.kts) into that folder to instantly add new features to your server!

Scripting Example

Backbone uses a modern Kotlin DSL. Below is a simple script showing how easily you can track data and handle events:

lifecycle {
    // This value 'survives' script reloads!
    var totalClicks by sustained(0)

    onLoad {
        println("Backbone feature initialized!")
    }

    // Listen to any Bukkit event instantly
    listener<PlayerInteractEvent> { event ->
        if (event.action.isLeftClick) {
            totalClicks++
            event.player.sendMessage("You've clicked $totalClicks times!")
        }
    }
}

Configuration

Backbone's main config is located at config/backbone/backbone.yaml. This file contains general settings for the plugin, such as enabling the update checker.

---
checkForUpdates: true # Enable or disable the update checker that notifies you of new versions of Backbone.
loggerCompatibilityMode: false # If true, Backbone will not use the new logging system and will instead log through the old Bukkit logger. This may be necessary for certain hosts that do not support the new logging system, but it is recommended to keep this disabled.

Admin Commands

Backbone is incredibly easy to manage from inside the game or your server console. Use the base command /backbone (or the shorter /bb alias) to access these tools:

Misc

/bb help <command>: Get help for a command.
/bb check-update: Check for updates.

Scripting

/bb scripting: See a list of all your custom features and check if they are currently running.
/bb scripting reload: Instantly apply any changes you made to your files without restarting the server.
/bb scripting enable <name>: Turn on a specific feature.
/bb scripting disable <name>: Turn off a specific feature.
/bb scripting wipe <name>: Completely reset the saved data for a specific feature.
/bb scripting probes: List all memory leak detection probes.
/bb scripting probes check-now: Run a memory leak check.
/bb scripting probes clear: Clear all probes.

Items

/bb item: View a list of all the custom items currently loaded on your server.
/bb item give <name>: Give yourself a specific custom item to test it out.
/bb item replicate: Instantly duplicate the custom item you are holding in your hand.
/bb item read: Scan the item you are holding to see its hidden background data.

Entities

/bb entity: View a list of all custom monsters or NPCs you have loaded.
/bb entity spawn <name>: Summon the custom mob directly at your current location.
/bb entity recreate-goals <radius>: Reload all custom goals for all custom entities in a given radius.

Integrations

PlaceholderAPI

If you use PlaceholderAPI on your server, Backbone automatically supports it! You can currently use the following tag in your scoreboards, chat formats, or menus:

%backbone_version%: Displays the version of Backbone your server is currently running.

(More placeholders are planned for future updates!)

Metrics

Backbone collects anonymous server metrics via bStats, an open-source statistics collection service for Minecraft servers. You may opt out with in /plugins/bStats/config.yml.

The metrics collected can be found here.

Backbone