Building your own Paths

You have learned about the Paths system, but now you want to build your own paths. This page explains how to do that.

The structure of a path

We've learned about the Paths system on the previous pages and now it is time to build our own path! To do that, you'll need to go to the Paths.yml file in the Autorank plugin folder.

The basic setup of a path looks like this:

Name of the path:    # Name of the path
    prerequisites:                    # The prerequisite section.
        some prerequisite:            
            value: value specific to the prerequisite
        some prerequisite 2:          
            value: value specific to the prerequisite
    requirements:                     # The requirements section.
        some requirement name:        
            value: values specific to the requirement
        some requirement name 2:      
            value: values specific to the requirement
    results:                          # The results section.          
        some result: 
            value: value specific to the result
        some result 2: 
            value: value specific to the result

It is important to carefully check your indentation (spaces and tabs)! Each section of a path has a level of indentation.

You can see that there are basically three important subsections of a path. You start off with the name of the path at the top, and then get to the three subsections:

• Prerequisites

  • Conditions that a player needs to meet to be eligible for the path.

• Requirements

  • Conditions that the player needs to fulfill to complete the path.

• Results

  • Actions that are performed after the player completes a path.

Note that these subsections are all located at the same level of indentation! It is very important that this is always the case because it's a specification of the YAML standard.

Your first path

Now that we know the structure of a path, can you decipher the path below?

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

Try to figure out what this path means, it should be familiar (if you've read the previous pages).

Answer

This path is called Running a marathon and requires players to move at least a thousand blocks to complete it (by walking). The player will need to walk as opposed to flying, swimming, or riding in a minecart. This is indicated by the zero behind the '1000', but don't worry about that for now.

To be able to activate this path, players need to be in the group Participants. Once the player has completed the (only) requirement of this path, the path is completed. Upon completion of the path, the player will receive ten thousand money (in whatever currency unit you use).

Note that Autorank will only check whether a player has completed a requirement if the path is active! When the player walks for a thousand blocks but has not activated the path, it will never receive the money.

Building your own path

Hopefully, you've got the hang of it now. One of the most frequent use-cases of Autorank is allowing players to gain ranks by playing on the server for a while. Due to popular request, we can work out an example here.

Ranking up based on play-time

Let's say we have the following ranks on our server:

• Default (new players start in this rank)

• Newbie

• Member

• Trusted Member

• Elite

Now let's say we want players to be able to rank up to a new rank after the following times:

• Default (new players start in this rank)

• Newbie (after playing for 2 hours)

• Member (after playing for one day)

• Trusted Member (after playing for a week)

• Elite (after playing for a year)

With your knowledge of paths, try to set it up using the path system! The answer is given below.

The &p tag is used to indicate the player's name. Whenever it appears, Autorank will replace it with the corresponding name of the player.

Newbie path

Newbie Path:
    prerequisites:
        in group: 
            value: 'Default' # Player is in the Default path to activate this path
    requirements:
        time: 
            value: '2h'
    results:
        command: 
            value: 'lp user &p parent set Newbie' # Set the player to Newbie rank

Member path

Member Path:
    prerequisites:
        in group: 
            value: 'Newbie'
    requirements:
        time: 
            value: '1d'
    results:
        command: 
            value: 'lp user &p parent set Member' # Set the player to Member rank

Trusted Member path

Trusted Member Path:
    prerequisites:
        in group: 
            value: 'Member'
    requirements:
        time: 
            value: '7d' # 7 days is a week!
    results:
        command: 
            value: 'lp user &p parent set Trusted Member'

Elite path

Elite Path:
    prerequisites:
        in group: 
            value: 'Trusted Member'
    requirements:
        time: 
            value: '365d' # 365 days is a year!
    results:
        command: 
            value: 'lp user &p parent set Elite'

You can also combine time units in the time requirement. When you define '1d 1h', it's the same as '25h'.

When you're finished, the Paths file should look like this:

Newbie Path:
    prerequisites:
        in group: 
            value: 'Default' # Player is in the Default path to activate this path
    requirements:
        time: 
            value: '2h'
    results:
        command: 
            value: 'lp user &p parent set Newbie' # Set the player to Newbie rank

Member Path:
    prerequisites:
        in group: 
            value: 'Newbie'
    requirements:
        time: 
            value: '1d'
    results:
        command: 
            value: 'lp user &p parent set Member' # Set the player to Member rank

Trusted Member Path:
    prerequisites:
        in group: 
            value: 'Member'
    requirements:
        time: 
            value: '7d' # 7 days is a week!
    results:
        command: 
            value: 'lp user &p parent set Trusted Member'

Elite Path:
    prerequisites:
        in group: 
            value: 'Trusted Member'
    requirements:
        time: 
            value: '365d' # 365 days is a year!
    results:
        command: 
            value: 'lp user &p parent set Elite'

If you're having trouble with Autorank recognizing your Paths file, make sure it is properly formatted. You can use this tool to check whether your syntax is correct.

Improvements to your paths

Now that we've built our first path, we might want to improve it a bit. Let's look into a few improvements!

Multiple requirements

Often you want players to fulfill more than one requirement to be able to complete a path. Let's take the example given above. You want a player to go from the Default rank to the Newbie rank when he's played for 2 hours and he's obtained at least 100 money. It's very easy to add additional requirements, see the example below.

Newbie Path:
    prerequisites:
        in group: 
            value: 'Default'
    requirements:         # There are two requirements in this section
        time: 
            value: '2h'
        money:
            value: 100
    results:
        command: 
            value: 'lp user &p parent set Newbie' 

Multiple prerequisites

Just like requirements, you can also use multiple prerequisites. Let's say we want a player to be in two groups at the same time before he is eligible for a path.

Path with two prerequisites:
    prerequisites:    # Player should be in the Default and Newbie group!
        in group: 
            value: 'Default'
        in group2: 
            value: 'Newbie'
# Requirements and results are left out for brevity

Whenever you want to use multiple of the same requirement (or prerequisite) you should give them a unique name, but still have the type name. The easiest way is to add a number at the end of the name, as Autorank will automatically remove the numbers. See the example above (both prerequisites are of the type in group).

Run a result when activating a path

Let's say you want to give the player something when they start a path; perhaps the path requires the player to walk a thousand blocks, so you surely want to give them some food before they embark on their long journey. To run results whenever a player activates a path, you'll need to add a new subsection to your path. See the example below.

Travel across the world:
    prerequisites:
        in group:  # Only travellers can undertake such a long journey.
            value: Travellers
    upon choosing: # New section that performs results when the path is activated
        command: 
            value: "give &p bread 5" # Give the player some bread
        message: 
            value: "Good luck on your journey."
    requirements:
        blocks moved: 
            value: 1000;0
    results:
        message:   # Tell the player they've done well.
            value: "You've become a true traveller!"

The upon choosing section can use the same results at the results section; Autorank is smart enough to understand that these are just results performed at an earlier stage of the path.

The path will perform the results that are specified in the upon choosing section. Note that the indentation matches that of the other sections!

Set a different display name for a path

Whenever a player activates a path or checks the progress on their path, they will have to use the name of the path as specified in your Paths.yml file. If you want to show a different name, you should not adjust the name at the top of your paths declaration! If you do, Autorank will think that it is a completely new path (and will kick players out of their current path). Instead, you should add a display name to the path, like so:

Very long and ugly path name: # DO NOT change this name
    prerequisites:
        # Some prerequisites here
    requirements:
        # Some requirements here
    results:
        # Some results here
    options:
        display name: "New path name" # Instead, add this to your path

The options section is used to configure additional options for a path. Note that it has the same indentation as the other subsections!

Run a result after fulfilling a requirement

Normally, results of a path are only performed when all of the requirements of a path are fulfilled. If you want to perform a result whenever a specific requirement is fulfilled, that is also possible. Let's say we want a player to get a new rank after he has completed multiple tasks (requirements), but also give him a small incentive every time a single task has been completed successfully. We can do that using the following example:

Get a new rank:
    prerequisites:
        # Some prerequisites
    requirements:
        mobs killed: # Kill a few spiders
            value: 50;Spider
            results:    # Get a small intermediate reward
                money:
                    value: 125
        mobs killed 2: 
            value: 20;Zombie
            results:
                money: # Get a small intermediate reward
                    value: 40
                message: # Encourage the player a bit more
                    value: "Good job on killing those zombies!"
    results:     
        money:     # Also get a large reward when all monsters have been killed
            value: 1000

Once a requirement has been fulfilled, Autorank will perform all results that are linked to that requirement.

As you can see, the example above gives the player a monetary reward whenever he completes a requirement. You can have multiple results for a single requirement (see the second requirement for example). When the player has fulfilled both requirements and hence has completed the path, the results of the path are performed (see the results subsection of the path) and he'll get 1000 money.

Optional requirements

What if you want a player to fulfill some requirements of a path, but not necessarily all of them to be able to complete the path. Autorank has a feature where you can mark a requirement as 'optional'. An optional requirement (or prerequisite) indicates that a player does not necessarily have to fulfill it to count it as complete.

Let's say you want players to walk a thousand blocks, but on the way, they may also gather some coal to get an extra reward. See the example below.

Walk a way:
    prerequisites:
        # Some prerequisites
    requirements:
        blocks moved: 
            value: 1000;0
        has item: # An optional requirement
            value: COAL;10
            options:
                optional: true
            results: # Give the player a bit of money for finding some coal
                money: 
                    value: 300
    results:
        # Some results

Note that has item requirement has its own result that is performed when the player fulfills the requirement, but this is not required whenever you set up an optional requirement.

This path will require players to walk at least 1000 blocks. In addition, they may also gather some coal (and be rewarded 300 money for it), but that is optional. They do not have to gather the coal to complete the path.

Just like requirements, prerequisites can also be optional.

Summarizing

You've read a lot about the Paths system and the way you can configure it. We believe most Paths can be made with these options. However, if you feel like you need an even deeper dive into the Paths system, feel free to continue to the next page.