How to configure the Paths.yml file?

The Paths.yml file is the most important file of Autorank. This file is used to define what paths (duh) you want to provide to your players. Since it is a YML, you should familiarize yourself with the YAML format. Many errors arise if you do not stick to this format.

If you want to skip ahead to any of the chapters, here's a neat list:

Without further ado, let's get started!

The Basics

As you probably know, Autorank works with paths. Each path has prerequisites, requirements, and results. Players can choose paths they like. However, a player can only 'choose' a path if he meets the prerequisites. When that's the case, the player choice will be 'locked in' and he will be able to complete the next stage of the path. It is important to know that Autorank allows players to have multiple active paths at the same time. Once a player has chosen an active path, he will need to meet the requirements to get the results.

Think of the marathon server example; we could make a path that rewards players based on the number of kilometers they have walked. However, we only want to reward players if they are in a group called 'Participants' (think of this like registering for a marathon). This path can easily be modelled by Autorank. You create a path, let's say 'Run a marathon' that has one prerequisite, namely that a player is in the Participants rank. Next, we add a requirement: a player has to walk for a total of 42 kilometers (about the length of a marathon). Lastly, we add a result: they will be rewarded with some money!

If you still can't follow, maybe this explanation will help!

Now, just to refreshen your mind, here's a general overview of the Autorank path system: How does Autorank work?

Implementation

Okay, so now that we've got the basics down, let's dive right into the action; how do we put this great idea (of a marathon) into an actual implementation? That's where the Paths.yml file comes into action. Instead of dragging you through a process of slowly learning the syntax, I'll provide an example of how we can put the marathon idea (see example above) into text:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        money: 
            value: 10000

Read through the example and see if you can understand it. Does it make sense? I feel as if it almost reads a bit like English! You can see that we defined a new path called 'Running a marathon'. It has one prerequisite, namely 'in group'. Pretty self-explanatory. Next up we have the 'blocks moved' requirement. It looks okay, but what does the ';0' behind the '1000' mean?

Autorank is pretty smart! It tracks many different types of movement, not only walking. In this case, the zero represents a type of movement; namely walking. You can use 1 (for moving with a boat), 2 (riding in a minecart), 3 (moving with a pig), etc. For a list of requirements and a detailed explanation, look at this page.

Improvements

Multiple prerequisites/requirements

It's nice to learn the basics and then implement a real-life model, but by now you only learned the very basics. Autorank is very powerful if you know how to use it properly! Let's extend our current model of a marathon path to include a sign-up fee. It would look more or less like this:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        money: 
            value: 10000

As you can see, it's quite easy to add new prerequisites. This works in this same way for requirements and results! To choose the 'Running a marathon' path, players need to be in the Participants rank and they should have at least 100 money (any valuta). However, currently, Autorank only checks if you have 100 money, but it does not subtract from the player's balance! Read on to fix this issue.

Running results when choosing a path

So let's remove some money from the player's balance and also give him a nice welcome message:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        money: 
            value: 10000

I added a new section called 'upon choosing': think of this as the results that are performed when a player chooses for a path with /ar choose . You can use the same results as in the 'results' section. Hence, I added a 'command' result that performs a command. The &p parameter can be used to specify the player's name (the one that is choosing the path).

Adding a display name to a path

We've made some nice changes, but it's still fairly inconvenient to type /ar choose Running a marathon to choose the path. Luckily, Autorank has a nice trick up its sleeve; you can specify a display name for a path. When a display name is specified, Autorank will display that name instead of the 'internal name'. Here's an example where I added a display name:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

A player can now perform /ar choose marathon to choose this path!

Using the 'optional' option

As I've said earlier, Autorank can be very powerful when you know how to use it! I'll show you what I mean. Running a marathon is difficult. It's also dangerous if you're not trained well. Let's put an extra prerequisite on our marathon path: we only want players to be able to choose this path if they are fit enough. Hence, we want them to have an 'acrobatics' level (of mcMMO) of at least 20. However, we still want untrained players to participate if they think they are up to it. How do we create such an optional prerequisite? Here's how to do it:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
        mcmmo skill level: 
            value: 20;acrobatics
            options:
                optional: true
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

Quite straightforward isn't it? We just added a 'mcmmo skill level' requirement and added an option to make it optional. We can do this for any prerequisite or requirement! By default, any requirement or prerequisite is not optional. Optional prerequisites will never be considered for completing or choosing a path (as they are optional), but it can be used as a guideline for players. Later on, I'll also show you a more meaningful way of using this optional option.

Using the 'auto complete' option

Let's say that I chose the marathon path, but I still need to complete the 'blocks moved' requirement. By default, Autorank will check every 5 minutes whether a player meets his requirements or prerequisites (this can be changed in the Settings.yml). Hence, Autorank will check every 5 minutes whether I walked 1000 blocks or not. If Autorank sees that I passed my requirement or prerequisite, it will mark it as completed automatically. In most cases, this is what you want: you don't have to check the requirement yourself which means less work for you as an administrator!

However, in some cases, you do not want this functionality. Sometimes you want players to perform some action before this requirement is considered as 'done'. Let's say we built a finish line with pressure plates at the end of the marathon track. We want this 'blocks moved' requirement to be checked only if they pass the finish line! Well, Autorank has got you covered. We can disable the auto-completion of requirement (or prerequisites) so that the player has to perform the /ar complete command after which Autorank will check his requirements. We can then hook up the pressure plates to a command block to perform the command for that player if he touches it. Here's how to do it:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
        mcmmo skill level: 
            value: 20;acrobatics
            options:
                optional: true
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
            options:
                auto complete: false
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

Again, pretty straightforward eh? By default, every requirement or prerequisite will auto complete. Putting 'auto complete: true' is, therefore, redundant. Note that you can also combine the optional and auto complete options together, like this:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
        mcmmo skill level: 
            value: 20;acrobatics
            options:
                optional: true
                auto complete: false
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
            options:
                auto complete: false
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

Now I've combined both options together for the mcmmo skill level requirement.

Having multiple requirements or results with the same name

You know, we added an optional requirement that requires that players need an acrobatics level of at least 20 to participate in the marathon. However, since athletes like to experiment with their bodies and strange (illegal) chemicals, we also want our runners to know a little bit about alchemy! 'No sweat Staartvin, we just add a new mcmmo skill level requirement!'. That's right ... well almost!

Unfortunately, the YAML format enforces this rule that you cannot have duplicate names. This means that when we add a new 'mcmmo skill level' requirement, it will conflict with the already existing 'mcmmo skill level' requirement as it has the same name! Luckily, I've developed a way around this: instead of just using the requirement name, also put a digit behind the name, like this: mcmmo skill level2. It can be any digit, it doesn't have to in the correct order. You can also do mcmmo skill level 309821098302198 (although that doesn't look that well in your file, but oh well). So, here's how I would do it:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
        mcmmo skill level: 
            value: 20;acrobatics
            options:
                optional: true
                auto complete: false
        mcmmo skill level 2: 
            value: 10;alchemy
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 1000;0
            options:
                auto complete: false
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

There you go! That works like a charm. Test it out and see for yourself :)

Adding results to a specific requirement

Remember that we have two ways of performing results? We can perform results by using the upon choosing section and when a path is completed with the results section. Well, there is actually yet another way to perform results!

Since running a marathon is an exhausting task, the runners may need some extra encouragement during the race. Let's give them a heartfelt message if they are halfway the race. Autorank allows you to define results that are performed when a player completes a specific requirement. We can add a requirement that sends a message when the player has walked over 500 blocks! Here's how I would do it:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
        money: 
            value: 100
        mcmmo skill level: 
            value: 20;acrobatics
            options:
                optional: true
                auto complete: false
        mcmmo skill level 2: 
            value: 10;alchemy
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved 1: 
            value: 500;0
            results:
                message: 
                    value: "You can do it &p, you're halfway there!"
        blocks moved 2: 
            value: 1000;0
            options:
                auto complete: false
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

Okay, this might be confusing right now. We added a new requirement 'blocks moved1', that waits for a player to walk 500 blocks and then sends him a message. I've renamed the original 'blocks moved' requirement to 'blocks moved2', since we need unique names for each requirement/prerequisite/result. Note that you cannot add results to a prerequisite, as there are already results being performed when the path is chosen!

Make a requirement world specific

Sometimes you want a requirement to only hold on a specific world. When we go back to the marathon example, you probably want the Marathon to be accessible on only one world. If no world is specified, all worlds are valid for that requirement. Here's a simple example:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
            options:
                world: marathonworld
        money: 
            value: 100
            options:
                world: marathonworld
        mcmmo skill level: 
            value: 10;alchemy
            options:
                world: marathonworld
    upon choosing:
        command: 
            value: "eco take &p 100"
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 500;0
            results:
                message: 
                    value: "You can do it &p, you're halfway there!"
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"

It's pretty simple, the prerequisites are now world specific!

Allow a player to complete a path multiple times

By default, once a player has completed a Path, he is prohibited from choosing that path again. In the case of our marathon path, a player can only participate (and finish) a marathon once. If you want players to be able to do path many times, you can add an 'is repeatable' option, like this:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
            options:
                world: marathonworld
    upon choosing:
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 500;0
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"
        is repeatable: true

At the bottom, you can see the new option in action. That's all there is to it. Note that the 'upon choosing' results will only be performed the first time a player chooses this path.

Automatically assign a path to a player

By default, a player has to explicitly choose a path by performing the /ar choose command. I can imagine that you want some paths to be automatically assigned to a player. Well, I've got you covered here (again)! Autorank can assign a path to a player if he meets the prerequisites of that path. In Autorank v4.2.3 and lower, priorities were used to determine which path would be assigned. However, in the latest versions of Autorank, the notion of priorities is removed.

Now here's how to allow a path to be automatically assigned to a player:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
            options:
                world: marathonworld
    upon choosing:
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 500;0
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"
        infinite pathing: true
        auto choose: true

The auto choose option has been added to the path. This will tell Autorank that the path may be automatically assigned to a player.

Only show a path in /ar view list when a player meets the path's prerequisites

Sometimes you want Autorank to show players only the paths they are able to choose (i.e. they meet the prerequisites of that path). It can be useful when you have many paths, but you want a player to only see a few paths that are relevant to them. If you want Autorank to do this, you can add a 'show based on prerequisites' option to the path. See the example below:

Running a marathon:
    prerequisites:
        in group: 
            value: Participants
    upon choosing:
        message: 
            value: "You are now participating in a marathon!"
    requirements:
        blocks moved: 
            value: 500;0
    results:
        money: 
            value: 10000
    options:
        display name: "Marathon"
        show based on prerequisites: true

As you can see, Autorank will only show this path in the /ar view list command when the player meets the prerequisites of that path.

Give a requirement a custom description

When a player performs /ar check, he is shown a list of requirements that he should meet. Each requirement has a small description to let the user know what to do. However, sometimes this description does not accurately portray what a player should do. Let's say that a player has to obtain 10 mob heads and will then get the permission 'mobhunt.complete' (by a third party plugin, not Autorank). You basically want to check if a player has this permission to see if he completed the mob hunt. Hence, you use a permission requirement, but you also want a custom description. Here's how to do it:

Completing the mob hunt:
    prerequisites:
        in group: 
            value: BountyHunters
    requirements:
        permission: 
            value: mobhunt.complete
            options:
                description: 'Complete the mob hunt!'
    results:
        money: 
            value: 10000

As you can see, a player will now see 'Complete the mob hunt!' instead of 'Have permission mobhunt.complete'.

Give a result a custom description

Much like setting a description for a requirement, as is shown here, you can set a custom description for a result. Here's how to do it:

Completing the mob hunt:
    prerequisites:
        in group: 
            value: BountyHunters
    requirements:
        permission: 
            value: mobhunt.complete
    results:
        money: 
            value: 10000
            options:
                description: 'Get a boat-load of cash!'

As you can see, a player will now see 'Get a boat-load of cash' when they try to view the path and its results.

Store progress of a path when a user de-activates a path

Using Autorank, players can choose to activate paths (using /ar choose) and can create progress on this path. However, they are also free to de-activate the path at any moment they like. Normally, when a player de-activates a path, his progress on the path is reset. This means that the player has to restart when he activates the path again. If, instead, you want the player to be able to start where he left off before de-activating the path, you can do the following:

Path with stored progress:
    prerequisites:
        in group: 
            value: SomeGroup
    requirements:
        permission: 
            value: have.some.permission
        money:
            value: 5000
    results:
        money: 
            value: 250
    options:
        store progress on deactivation: true

Toggle whether a path can be partially completed or not

In previous versions of Autorank (4.2.3 and lower), you could only set whether all paths could be completed in steps or not. In Autorank v4.2.4 and up, you can set whether a player can complete a path partially on a per-path basis. Let's say you want a player to be able to progress on a path and then deactivate the path for a bit. By default, all paths allow partial completion. If you want to disable the behaviour mentioned above (note that this means that a player can only complete a path if he meets all requirements of that path at the same time), you can do so by adjusting the option 'allow partial completion', see the example below:

Path where all requirements should be met at the same time:
    prerequisites:
        in group: 
            value: SomeGroup
    requirements:
        permission: 
            value: have.some.permission
        money:
            value: 5000
    results:
        money: 
            value: 250
    options:
        allow partial completion: false

Note that this means that a player can only complete the path once he meets the permission and money requirement at the same time! If partial completion is turned on for the path, the player could first complete the permission requirement and later on complete the money requirement (while not meeting the permission requirement at that specific moment in time).

Make a result only perform when a path hasn't already been completed before on another server.

Assume that you have the same path on multiple servers. Let's say this path is called "A to B". Whenever a player completed this path, the player should receive the results, but these results differ per server. You would set up a path (with the same internal name) on both servers. Make sure to connect Autorank to a database (so it can store data between the servers). When a player has completed a path on server A and joins server B (to complete the path there), Autorank will detect that the player has already completed the path and so it will only perform the results that are deemed 'local'. A local result means that it will always be performed when the completed its corresponding path. On the contrary, a 'global' result will only be performed if the player hasn't already completed the path before on another server. See the example below

A to B:
    prerequisites:
        in group: 
            value: SomeGroup
    requirements:
        permission: 
            value: have.some.permission
        money:
            value: 5000
    results:
        money: 
            value: 250
            options:
                global: true

If a player completes this path for the first time, they will receive the money. If they join a second server and complete this path again (provided it has the same name on both servers), Autorank will not give them the money again. For this to work, you'll have to enable MySQL in the Settings.yml!

Have a cooldown on a path

If you want your players to complete a path multiple times, but not immediately after it has completed the path, you can set up a cooldown. This will prevent the player from choosing the path again within a certain time period. The time period is configurable. See the example below:

A to B:
    prerequisites:
        in group: 
            value: SomeGroup
    requirements:
        permission: 
            value: have.some.permission
        money:
            value: 5000
    results:
        money: 
            value: 250
    options:
        is repeatable: true
        cooldown: 5d 10h

This path can be repeated by players, but they have to wait 5 days and 10 hours after completing it before they can start the path again. Make sure you don't forget to add the 'is repeatable' option, otherwise this wouldn't make any sense (cooldown only applies to paths that are repeatable).

Bring me back to the homepage!