Quickstart

Mike Liu edited this page Jul 5, 2018 · 20 revisions

Making a Protected Spawn Region

Here is a simple way to make a spawn region that only you can modify. Note that this is one of the many ways that you can go about this task. This quickstart is meant at getting you familiar with the process of setting up protection for your world and server.

Overview

In order to make all this work, you need to:

  1. Create a region.
  2. Create and configure a Handler.
  3. Link the region and Handler together.

If that doesn't make any sense, read on.

The State Buffer

Before you can start, you need to familiarize yourself with something known as the state buffer. The state buffer is a collection of data tied to each individual user that is used in several of the commands. You add things to the state buffer, which is then used in some commands. This data isn't permanent, and is lost between server restarts and commands that use its contents. For example, when defining regions, many of the different types of regions take one or more positions in order to define their boundaries. The Rectangular region, for example, takes a list of positions and finds the rectangular area that contains all of those positions. The simpler regions all tend to have this behavior.

To check the contents of your state buffer, use

/foxguard current

At this point, your state buffer should be empty, because you haven't put anything into it. Let's add a position to it then. Go to a corner of your spawn area, and type

/foxguard position

to add your current position to the state buffer. Now if you type

/foxguard current

again, you'll see that position on the list.

If you want to clear out your state buffer, just type

/foxguard flush

Remember, you can type

/foxguard current

at any time to check your state buffer to make sure that everything is in order.

Making a Region

A region in FoxGuard is just an area. Any point in any world will either be inside or outside a region. Regions are only responsible for defining areas of effect, and are not actually responsible for protecting the areas they define. A world-region is a specific kind of region that is contained within a specific world. We will start by making a rectangular world-region around our spawn area. A rectangular world-region is a two-dimensional region that extends vertically all the way to the top and bottom of the world. It tends to be a very simple and effective region for use in spawn areas.

Go ahead and add two points: One at each corner of your spawn area. Alternatively, you can move around the perimeter of your spawn area and keep adding points. Just remember that the resulting rectangular region will contain ALL of those points.

If you accidentally add a point you didn't mean to, you can remove it. Type

/foxguard state position remove

to remove the last position from your state buffer or use

/foxguard state position remove <index>

to remove a specific entry. Indexes start at 1.

Once you have all your points in your state buffer and have made sure they are correct, it's time to actually create a region.

Type

/foxguard create worldregion <regionname> rectangular

This makes a new world-region with a name you specify (Names must be alphanumeric and they must not start with a number.) of type rectangular. World-regions are placed in the current world by default, which is exactly where we want it.

You can type

/foxguard list regions

to see the list of current regions. You should see a couple global regions highlighted in yellow and magenta along with the region you just made.

A quick note on global regions. They are used to define rules globally (Such definition. So descript. Very wow). There are two kinds of global regions. A world-global region applies to an entire world, and there is one for each world. The super-global region applies to every point in every world, or effectively, the entire server. They both cannot be deleted or renamed, but can be otherwise used like user-created regions.

You can also type

/foxguard detail region <regionname>

to see detailed information on a certain region. Go ahead and try it on the region you just made. If the output looks good, then it's time to move onto the next step!

Making a Handler

Now that we have made a region, we need to control what happens in the region. As pointed out earlier, regions do nothing to actually control the areas that they describe. To do that, we use handlers. Handlers are objects that respond in some way to events without being concerned about where they actually happen. (Some specialized handlers can be location sensitive, but we won't be using them in this tutorial.) The handler we will be using in this tutorial will cancel or allow an event.

In other words, handlers, similar to regions, cannot function on their own.

When handlers handle events, they can respond with either allow, deny, or passthrough. This will be explained a little bit more later.

We will be using the basic handler for this tutorial. It is a general purpose handler and good for many things.

There generally isn't any special preparation before creating a handler, so go ahead and type

/foxguard create handler <handlername> basic easy

This makes a new handler of type basic with the name you specify, using the easy template. This template does most of the structural setup of the handler for you, so you can start configuring the flags immediately. The command also assigns it a priority of 0. Handlers are not tied to any particular world. This makes them usable across several worlds.

Note on priorities. When more than one handler is notified of an event, they may not always give the same response. This is where priorities come in. A handler of a higher priority ALWAYS overrides a handler of a lower priority. If they are the same priority, "DENY" has priority over "ALLOW." A handler may, however, abstain from making a decision (Letting the event "passthrough"). If all the handlers at a priority level ignore the event and let it passthrough, then the lower handlers are queried. If all handlers passthrough. The global handler decides the result.

If you type

/foxguard list handlers

you can check to make sure that it was successfully made.

Type

/foxguard detail handler <handlername>

to get details on the handler. You will also notice that your username will be on the owners list. By default, all events passthrough. You can configure flags for each individual group. If you are both an owner and a member, the permissions from both groups apply to you, with permissions from the owner group taking priority (multiple groups are evaluated top to bottom, like a ladder system).

To add someone to a group, type

/foxguard modify handler <handlername> users [groupname] add [usernames]...

To remove someone, type

/foxguard modify handler <handlername> users [groupname] remove [usernames]...

If you are using the minecraft client, you can click on the text from /fg detail to add players too. Any text with a hover bubble is clickable. Try it!

Now you've set up a handler to control what should happen in your spawn area, but it still doesn't work yet.

Linking Regions and Handlers

This is where most of magic happens. It should be pretty obvious now that regions and handlers compliment each other. You may have also noticed the "Linked Handlers" section when you typed

/foxguard detail region <regionname>.

Essentially, you link regions to handlers to make them work.

Regions can be linked to multiple handlers and multiple regions can be linked to the same handler. Here's a breakdown of how it all works together.

When an event happens, such as when a block is broken, it happens inside one or more regions. These regions are then used to make a list of all handlers that should be concerned about this event. It does this by looking at the linked handlers of every region, ignoring any duplicates. It then goes through this list of handlers starting at the highest priority and working downward. The first priority level which evaluates to something other than passthrough determines the result of the event.

So in order to protect our spawn area, we need to link the spawn region to the handler we made.

There are two ways of doing this.

The One-liner

/foxguard link <regionname> <handlername>

The Longer Way

This method makes use of the state buffer.

/foxguard state region add <regionname>

/foxguard state handler add <handlername>

/foxguard link

This method is useful because it allows you to link multiple regions to multiple handlers all at once. For example if you have 3 handlers that you want to apply to 3 different regions, you could just add all of them to the state buffer and use

/foxguard link

to link all of them at once.

Wrapping Up

Go to your spawn area and test to make sure the protection works. Once you've done that, type

/foxguard save

to save your configuration. FoxGuard stores its configuration in the world folders under the "foxguard" directory by default. Each region and handler has its own directory. This directory will contain a metadata file, as well as any other files and folders that the region/handler needs to store its own data. Some regions and handlers will use plain text config files, allowing you to edit them by hand if you so please. Deleting a metadata file will cause that entire region/handler to be removed.

Going Beyond

Yay! You have a working spawn protection!

As this wiki expands, take a look at the other features available in this plugin. Also feel free to type

/foxguard help

to see the full list of commands and

/foxguard help <command>

for help on a specific command.

Have fun!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.