Getting started

Getting started with bucket variables starts with creating a namespace, learn about them in this page.

Namespaces

To use bucket variables, you must first create a namespace.

The name of the namespace must be globally unique across DiamondFire.

As the namespace owner, you control which plots have access to your namespace.

Once your plot has access to a namespace, you’ll need to add it to your plot and assign an alias.

Namespace Aliases

Namespace aliases are set per-plot, and are how you refer to namespaces in your code; this does not need to be unique across DiamondFire, so choose whatever is convenient.

Note

Namespace aliases are useful in setups where you clone code from a development plot to a main plot.

While the code across both plots is the same and refers to the same alias, that alias can map to different namespaces on the dev and main plots, ensuring your saved data remains separate.

Creating a Namespace

To create a namespace and give your current plot access to it, you can use:

/plot namespace create <namespace> <alias>

If you want other plots to have access to the namespace, you can add them with:

/namespace whitelist add <namespace> [plot]

Caution

You can delete namespaces with:

/namespace remove <namespace>

This will delete all data inside the namespace, and cannot be undone!

Bucket Variables

To load (or create) a bucket, use the Load Bucket action in the Set Variable block. (Note: This is a Suspending action). Once the bucket is loaded, you can use bucket variable items just like standard saved var items. You can save the values persistently using the Save Bucket action, and unload the bucket using the Save and Unload Bucket action.

Each bucket var will reference a namespace and a bucket name. You can get bucket vars with:

/bvar [namespaceAlias] <bucket> <name> [amount]

Note

If you don’t specify a namespace alias, your plot’s default will be used. The first namespace you create is automatically the default; you can change the default namespace using:

/p namespace setdefault <namespaceAlias>

Recommended Usage

The most common use of bucket variables is per-player data, with each player having a bucket. You Load the bucket (for example data-%uuid) on player join, Save it periodically, then Unload when the player quits.

Note

If players leave during a LagSlayer freeze, you can ensure their buckets are still unloaded by using the Get Loaded Buckets action to get all loaded buckets, then Unload buckets for players who aren’t online (who left during the LagSlayer freeze).