Updating the Plugin
When the plugin updates, it's likely that some localization keys will be added, some changed, some even removed. All required changes will be included under the "Localization Info" section.

NB! It is recommended to use a YML editor to add/remove keys, since the keys need to be indented correctly.

NB! After you've replaced the old plugin jar file with the new one, reload/restart the server, and run
and
This will ensure, that all language changes are up-to-date.





General Info
In general, the game process is quite simple. As in the real thing, you on the course you've built, pass checkpoints, shoot at the shooting range, and finish your run by crossing the finish line. BiaMine handles these things using many internal utilities, that make it easier for you to set up.

The Starting Area
Usually, the first thing you'll want to do, to set up BiaMine with your course, is mark the starting area. In the original plugin, you'd just mark one block, and all players would be then teleported to that position. That, however, does not scale very well. For that reason, BiaMine: Reloaded allows to define a starting area. Instead of a single point, you mark 2 corners of a cuboid, to which the players will be teleported.

Prep & Final Countdown
Before the game starts, there is one more phase - the prep phase. When you're creating your BiaMine: Reloaded game instance, you'll get to define the duration of both the prep duration, and the final countdown.

Simply put, when you start a game, at first players will be given time to prepare for the run - equip the armor, check the course, whatever they need [and you allow them to].

After the prep period, the final countdown will begin. The players can be optionally frozen with the slowness effect (enable/disable in the config file),
and then, once the countdown finishes, they'll be released.

Checkpoints
It's likely you'll want to add checkpoints to your game. BiaMine: Reloaded handles checkpoints in a much different fashion, than the original did. When adding checkpoints, you'll define a cuboid, by marking the lower and upper bounds. The plugin will then know, that once a player enters that area, they've passed a checkpoint.
The finish line is internally also considered a checkpoint, and therefore when adding checkpoints, add one to set as the finish line.
Checkpoints can also be named. Internally, the checkpoints are saved under IDs, that follow this scheme: checkpoint[n], where [n] is the order number. Managing checkpoints is also accomplished via these IDs. If you, however are not sure which checkpoint is which, the "show" option will show you the provided checkpoint's position.

The Finish Line
As mentioned before, internally, the finish line is just a checkpoint, that has been marked as a finishing checkpoint. Upon reaching the finishing checkpoint, as long as all of the required laps have been finished, the player will finish the game and be excluded from all following communication intended for the participants of an active game.

The Shooting Range
Though optional, BiaMine: Reloaded introduces a new feature to the game process: The Shooting Range. Each game has their own shooting range configuration, and therefore they do not interfere. That however also means, that each game has to have it's own physical shooting range, and cannot share shooting spots / shooting targets with another shooting range.
By configuring the shooting range, you can mark targets and shooting areas, that the plugin will then track. The generated game report will also contain each player's shooting stats. The Shooting Range is optional, meaning if you just don't set it up, it won't interfere with your game process.

The Scoreboard
Though a scoreboard was provided in the original BiaMine, it was short of any customization, and worked in a weird fashion. It's inner workings were inefficient, bad and in general, clunky. BiaMine: Reloaded solves this problem, and adds the ability for each game to have a customized, fully adjustable, and most importantly, localized, scoreboard. Such functionality is accomplished by using scoreboard configurations. A scoreboard configuration stores all of the contents of the scoreboard and is therefore easily reusable and reassignable.
Managing scoreboards is done via /sconfig
NB! BiaMine: Reloaded does not restrict changing the language, so technically it is possible to change it while the game is running. HOWEVER - internally, the scoreboard for a game is only fully initialized, and therefore refreshed at the start of a game. While the language will be changed, the scoreboard will not reflect that change. It is therefore not recommended to change the language while a game is running.

Placeholders
As an addition to the scoreboard, there exist many different placeholders, that can be used within the scoreboard. These placeholders are as follows:

• %timer%
• %playersFinished%
• %playersNotFinished%
• %playersParticipating%
• %shootings%
• %header%
• %footer%
• %date%
• %dateTime%
• %localTime%
• %state%
• %bestTime%

The plugin also supports a brand new concept - custom placeholders, also referred to as global placeholders. These are definable in the configuration file, and can contain whatever you want them to contain.
NB! It is important to note, that these cannot contain built-in placeholders. These will not be replaced. Global placeholders are meant to allow to easily add repeating pieces of text, without the need to actually type them out every time.
Global placeholders have to start with an underscore to be recognized by BiaMine.
A detailed table with all the placeholders, including their allowed usage areas and descriptions are included in the plugin config file.

Order of operations
The order of operations on startup of a BiaMine instance is as follows:

1. Teleport players to the starting area.
- All players are teleported to a position within the starting area.
2. Start prep
- The preparation timer starts.
3. Halt players
- Skipped, if disabled in the config.
4. Final countdown
- The final countdown is started.
5. Players are released
- If players were previously halted, they are released.
- Game timer is started, and the game process begins.
After this sequence concludes, a scoreboard refresh task is initiated to keep the scoreboard info up to date. BiaMine starts registering checkpoint passes, and all other area-related stuff.

How can one create a game?
The following section describes the creation of a standard BiaMine Biathlon game.

1. Creating an instance
The syntax to create a game called testgame is as follows:
This command creates an instance "testgame", with a 30-second prep, 10-second final countdown, and the display name of " Test Game"
Once you've got an instance, you're good to go on to the next step.

2. Setting the starting area
For the plugin to know where to teleport the players, you should set a starting area. For this task, /setstart exists.
Stand on the lower corner of the starting area, and use
This should set the first boundary coordinate.
Then, stand on the upper corner of the starting area, and use
With this, you should have a working starting area.

3. Adding checkpoints
While adding checkpoints is optional, one of them should always be present.
Since internally, the finish line is handled the same way as a checkpoint is, you add the finish line as a checkpoint, and then mark it as the finishing checkpoint.
To add a regular checkpoint, do the following:
This will simply add a checkpoint to testgame's internal checkpoint list. It's not there yet though.
Marking a checkpoint is similar to the way we marked the starting area.
Use to set the first corner of checkpoint1 to your position.
Similarly, use to mark the other corner of the checkpoint. Valid bounds are only 1 or 2, using any other number will not yield any success.
Optionally, you can change the display name of the checkpoint. This can be accomplished by using

Code (Text):

/checkpoint testgame setname checkpointID <name>

and replacing <name> with the desired name.

To add a finish line, or a finishing checkpoint, do the following:
1. Add a regular checkpoint, by following the same steps that are used to add a checkpoint. For the purposes of this tutorial, checkpointID will be used to represent the identifier of the checkpoint.
2. Now, to mark a checkpoint as the finish line, use .
With this, you've marked the finish line for your game.

NB! Checkpoints are always accessed using their ID, which consists of the word 'checkpoint' and a number representing their order in a game's checkpoint list. It is recommended that the checkpoints are added in the same order.

3. Enabling the dispenser module
I'm really only calling it a module, because nothing breaks if you don't set it up.
The Dispenser is a system, which you can use to dispense items to players when the game starts. Setting it up is fairly simple.
NB! Each game has it's own dispenser list, so it is not required to create one beforehand.

All operations related to The Dispenser are performed using .
To add an item to a game's dispenser configuration, use the following command:
where <item> is the id of the item you wish to add.
NB! Including the vanilla "minecraft:" prefix is not necessary.

Removing an item is accomplished in a similar fashion.
where <item> is the id of the item you wish to remove.

Auto-determine
There exists a special option when it comes to determining the amount of items to dispense. That option is auto.

The command to enable/disable the auto-determine function for an item is as follows: , where <item> is the item you wish to use.

If you set the item amount to be automatically determined, the amount will be calculated using the following formula:
NB! This also means, that auto-determine will only work if the game has a Shooting Range.

4. Setting up a shooting range
As previously described, each game can have it's own shooting range.
First, a shooting range consists of shooting spots and shooting targets.
Therefore, each shooting spot has it's own shooting targets and therefore, a shooting target can only belong to one shooting spot.

To add a shooting spot, first register is using
This will add a shooting spot. Mark it's area using , where X is the boundary you wish to set and spotID is the spot you are setting the area for.
As always, stand over the block the coordinates of which you wish to use.

To add a shooting target, do the following:
Run .
NB! After running this command, you'll have 10 seconds to right-click a block you wish to set as the target.

Removing a target is done in a similar fashion:
Run NB! After running this command, you'll have 10 seconds to right-click a target you wish to remove. The block will not be broken.

It is also possible to view the information for individual targets. For that, use and once again, click on the block you wish to check.

With this, the Shooting Range has been configured.

5. Modifying the scoreboard configuration
Each game may also use it's own scoreboard config. A scoreboard configuration defines what is shown on which line, and how it is presented.

NB! This section describes the process of creating and managing a new scoreboard config. Each game is automatically assigned a default config, so if you're happy with the existing one, there's no need to create a new one.

All scoreboard configuration related operations are performed using To create a scoreboard configuration, use , where <id> is the id you'll use to edit/access the config.
Once you've created the config, use Editing a scoreboard config is accomplished in the following manner:
- Setting the properties of a line
- Moving the existing properties within the scoreboard

Setting the content of a line is done as follows:
, where X is the line number, and <property> is whatever you wish to set the line to.
NB! You may wish to read the Placeholders chapter before setting the content of a line.

Moving the existing properties within the board is an option when the config is already ready, and you wish to switch around a few lines.
Moving the lines is done as follows:
, where <id> is the config you're editing, <property> is the content of the line you wish to move, <operation> is the operation you wish to perform, and <param> is either the number of lines or the new content.
Available operations:
- moveTo which moves the line with the content you provided to the specified line
- raiseBy which raises the line with the content you provided by a number of lines you provide
- lowerBy which lowers the line with the content you provided by a number of lines you provide
- changeTo which changes the content of the line which contains the content you provided to whatever you specify
- setPropertyTo which operates on lines directly - this will set a line's property to whatever you specify.

NB! It is incredibly important to note, that all operations except setPropertyTo do not work with the lineID, but rather search for the line with the content you provide. Therefore, the tab completions line1-line8 are only meant for the setPropertyTo operation.
NB! This will very likely be reworked in the future.

Assigning a scoreboard config
After you've done all you want to the config, you may assign it using
, where <confID> is the scoreboard config you wish to assign, <gameID> is the game you want to assign the scoreboard config to, and [-ra] is an optional parameter, that you can use if you wish to reassign instead of assign. Reassigning will unassign the scoreboard config from all other games that have been assigned this scoreboard config, and then assign this config to the target game.

This concludes the instructions for the scoreboard.

6. Starting the game
Once you've completed all previous steps, you can start the game with
, where <shootings> is the number of shootings in the game. You may optionally include a list of player names, if you wish to only include a select group of players.


Localization
BiaMine: Reloaded has a localization system similar to the original plugin's system. Internally, there is a utility that reads the language files, and takes the phrases it needs from them. For you to provide your own localizations, the following needs to be done:
1. Create a copy of the included en-US.yml file. This contains all of the text the plugin uses.
2. Rename the file to the language code you will be translating into (en-GB, ru-RU etc.).
3. Translate the contents - the phrases are preceded by a key. This key should never be edited, changed, or removed. These are the keys with which the plugin can access the phrases.
4. Don't forget to modify the language name at the top of the file.
5. Now, add the language code (or the filename without the extension) to the language list in localization.yml.
6. Reload the server, or use /biamineutil reloadLocalizations to apply the changes.
7. The language can now be changed using /setlanguage.
NB! If your language code is not visible in the autocomplete list, use either /biamineutil reloadCurrentLanguageFile or /biamineutil reload to make sure the changes have been applied.

Commands
BiaMine has a lot of different commands for different purposes. They are detailed here.

/createbiathlon <gameID> <preparationTime> <finalCountdown> <displayName>
Purpose: Creating a new BiaMine game instance
Permission: biamine.admin

/deletebiathlon <gameID>
Purpose: Deleting a BiaMine game instance
Permission: biamine.full

/setlanguage <langCode>
Purpose: Changing the plugin language
Permission: biamine.admin

/startgame <gameID> <shootings> [players...]
Purpose: Starting a BiaMine game instance.
Optional parameter: Players. May be omitted, to instruct BiaMine to use an exclusion list instead.
Permission: biamine.admin

/pausegame <gameID>
Purpose: Pausing a BiaMine game instance.
Permission: biamine.admin

/resumegame <gameID>
Purpose: Resuming a BiaMine game instance
Permission: biamine.admin

/terminate <gameID> [reason]
Purpose: Terminating an active BiaMine game instance
Optional parameter: Reason of termination. Not required.
Permission: biamine.full

/kickplayer <player> [reason]
Purpose: Kicking a player from an ongoing biathlon game.
Optional parameter: Reason of kicking. Not required.
Permission: biamine.admin

/rejoinbiathlon
Purpose: Attempting to rejoin to a biathlon game.
Permission: biamine.player

/exclusionlist <create|edit|assign|delete> <...>
Purpose: Creating, managing and assigning of exclusion lists.
Permission: biamine.full

/checkpoint <gameID> <add|remove|find|show|list|setbound|setname|setfinish> <none|id|bound>
Purpose: Managing checkpoints for an existing game
Permission: biamine.full

/setstart <gameID> <bound1|bound2>
Purpose: Setting the starting area for a BiaMine game instance.
Permission: biamine.admin

/listgames
Purpose: Viewing created BiaMine game instances.
Permission: biamine.admin

/biaedit <gameID> <property> <value>
Purpose: Editing existing BiaMine game instance properties.
Permission: biamine.admin

/biamineutil <operation>
Purpose: Performing utility operations for plugin troubleshooting/maintenance
Permission: biamine.full

/dispenser <gameID> <addItem|removeItem|show|enableAuto|disableAuto> <item>
Purpose: Managing, modifying or viewing of the Dispenser configuration for a game.
Ambiguous options
1. enableauto: enable automatic calculation for an item's amount.
2. disableauto: disable automatic calculation for an item's amount.
Permission: biamine.admin

/shootingrange <gameID> <addSpot|editSpot|removeSpot|visualiseSpots|showInfo> <...>
Purpose: Managing, modifying or viewing Shooting Range options for a game
Permission: biamine.admin

/biainfo <gameID>
Purpose: Viewing information about a BiaMine game instance.
Permission: biamine.admin

/sconfig <create|edit|delete|list|clear|assign> A<...>
Purpose: Managing, deleting or assigning scoreboard configurations for a game.
Permission: biamine.admin

Extras

1. Exclusion lists
If you wish to start a game without needing to require the exact players, there is an option to only include the players you don't want to participate. For that purpose, exclusion lists exist.
Creating one is easy - similarly to other features, exclusion lists are stored using an ID. To create a exclusion list, use

Code (Text):

/exclusionlist create <id>

where <id> is the ID you assign the list.
Management is accomplished using

Code (Text):

/exclusionlist edit <id>

There are 2 options:
- addPlayer adds a player to the exclusion list
- removePlayer removes a player from the exclusion list
NB! These operations take in another parameter - the player name.
Example:

Code (Text):

/exclusionlist edit <id> addPlayer <player>

Assigning an exclusion list is as simple as running the following:
where <list> is the ID of the exclusion list, and <gameID> the game you wish to assign the list to.
Similarly, unassigning is accomplished by running the same command, but using instead of
2. Alternate phrases
The Localization chapter focuses on creating custom localizations, but there is an aspect of the Localization System that is not touched in that chapter.
Since every new localization file is only detected if added to the localization.yml file, it is possible to add text files with custom phrases to be used instead of the plugin's default ones.
For example, if you wish to replace the checkpoint pass messages, you may copy the default language file (en-US.yml), replace the messages in it, and add it to localizations.yml. That way you're able to replace every message the plugin sends with whatever you wish.
NB! Do keep in mind, that a phrase can only contain the placeholders it contains in the original variant.

3. Utility operations
The plugin has a utility command called /biamineutil. It is a utility command, that allows to perform troubleshooting operations.

* resetDefaultLanguageFile
- Resets the default (en-US.yml) file to the one included with the plugin.

* refreshFiles
- Reloads all .yml files the plugin uses.

* refreshActiveScoreboard
- Refreshes the info shown on an active scoreboard. Only works while a game is active.

* resetScoreboard
- Resets the scoreboard, in case it's been left on screen due to an unexpected shutdown/termination of an active game.

* printActiveGameID
- Sends you a message with the ID for the currently active game, if any.

* reloadLocalizations
- Runs localization discovery, rechecking newly added localization files.

* rereadConfig
- Rereads the configuration file (config.yml)

* reloadCurrentLanguageFile
- Reloads the currently active language file. Useful after changing anything in the config.

* reload
- Reloads all plugin files (not the same as /reload)

* clearCustomBlockData
- Not included in tab completion. Removes all saved shooting target data from blocks in the chunk the executor is.

4. State control
It is possible to pause/resume an active game. For that, there exist two commands.
where <gameID> is the game you wish to stop. Since only one game can be active at any given time, the command tries to pause the active game. The <gameID> parameter will be removed in the future.

A paused game can also be resumed by using the following command:
where <gameID> is the game you wish to resume.
This command will start a countdown (configured in config.yml), after which the game will be resumed.

5. Termination
A game can also be terminated. If you wish to stop an active game for any reason, you may use
Termination force-stops the game without saving states, stats or other game info.

6. Preventative Termination
[PREVTERM] or PREVentative TERMination, is a fault-prevention mechanism built into BiaMine: Reloaded. Whenever you attempt to start a game in an incorrect/incomplete state, or with core aspects missing, [PREVTERM] will stop any further actions, and display a message on what triggered the termination. That prevents data corruption, wrong data from being saved, or any and all further issues that could happen if a game is started in an incorrect state.

7. Game Reporter
BiaMine also has a reporting tool built-in. When a game is active, many aspects of it are recorded. The report file gives you an opportunity to review different parts of the biathlon game, and spot any inconsistencies/cheating.
The following is recorded:
* checkpoint reaching times
* shooting start and end times
* shooting segment duration
* shooting stats (misses, hits, arrow count)
* participants
* leaderboard