Home

Introduction

GameStages is a framework for creating progression systems in Mod Packs. These progression systems are built around stages which are named flags that can be given to or taken from players. On their own stages have no meaning or functionality, it is up to you to create this meaning by configuring other mods. Many mods can be configured to react differently to players based on the stages they do/don't have.

Features like locking crafting recipes or preventing certain mobs from spawning are provided by 3rd party addons. This mod only provides the tools and interface required for these addons to communicate with each other. The following features are built into GameStages.

• API - A central interface used by other mods to access stage data.
• Commands - Used to access stage data while in game.
• Networking - Stage data is kept in sync with the server.
• Serialization - Stage data is saved to disk and will survive restarting the game.
• CraftTweaker Integration - CraftTweaker scripts can interface with stage data.

Getting Started

The first concept to understand is that stages are not created or registered. A stage is simply a named flag that can be granted to players on demand. These names can be up to 64 characters long and must only contain the lowercase alphabet, 0-9, underscore (_), and colons (:). On it's own a stage has no meaning or functionality, players can not obtain it, and obtaining it will do nothing. It is up to you to provide these mechanics through your pack configuration.

The most common way to grant stages is through commands. This is because commands are very flexible and can be executed in a wide variety of ways such as advancement completion rewards. Mods like Better Questing also allow commands to be run as quest rewards. Imagine that you want to grant a player stage one when they complete some task in your pack. You would simply create an advancement or quest related to that task and then run the command /gamestage add @p one as a reward. In Minecraft @p is a special argument that is substituted with the name of the player that triggered the command to happen. In the case of advancements it's the player who unlocked the advancement.

Now that players can obtain the stage you need to give the stage meaning. This is commonly done through GameStage addons that allow you to configure special properties for various stages. For example the mod Dimension Stages allows you to prevent players from entering a dimension unless they have a specific stage. These addons commonly use CraftTweaker scripts to configure these mechanics.

Commands

GameStages provides a variety of commands for accessing the GameStage data. Commands provide a flexible interface for GameStages as they can be used by a wide variety of game mechanics including many custom mechanics added by mods.

Command Legend

Text Type	Meaning
plaintext	Enter the text exactly as it is written.
<variable>	A required variable, replace with your value.
(optional)	An optional variable. Replace with your value or skip it.

Command List

Command	Op Lvl	Description
/gamestage add (silent)	2	Grants a stage to a player. If silent the player will not be told.
/gamestage remove (silent)	2	Revokes a stage from a player. If silent the player will not be told.
/gamestage info (player)	0	Lists all stages that the player has.
/gamestage clear (player)	2	Removes all stages from the player. If no player is specified the user will lose their stages.
/gamestage all (player)	2	Gives all known stages to the player. If no player is specified the user will be given the stages.
/gamestage check (player)	2	Checks if the player has a stage. If no player is specified the user will be checked.
/gamestage reload	2	Causes GameStages to reload all of it's own data.

Known Stages

The known stages file provides an optional way to define the list of all stages used by your mod pack. Defining your stages here is optional but highly recommended. Commands will pull from this list to populate the autocomplete and suggestion list. This list is also used by the /gamestage all (player) command to grant all stages to the player. In some cases using this file can also help spot typos in your configurations as unknown stages will trigger a warning. The file can be created at ~/config/gamestages/known_stages.json and should hold a simple array of strings. The /gamestage reload command will reload this file. The contents of an example file would look like this.

["one", "two", "three"]

Fake Players

Fake players are used by mods to stand in for the player for things like automation. Fake players are unable to unlock stages so this mod provides a way to define default stages for them. This is done by editing the ~/config/gamestages/fake_players.json file or creating it if it does not exist. Here is an example file.

[
  {
    "fakePlayerName": "test123",
    "stages": [
      "stage1",
      "stage2",
      "stage3"
    ]
  },
  {
    "fakePlayerName": "fake456",
    "stages": [
      "fish",
      "pepper",
      "cheese"
    ]
  }
]

Mod Support

If you are a mod author, this section of the documentation is for you!

Getting Started

To get started you need to add GameStages to your developer environment by modifying your Gradle build script.

repositories {

    maven { 
        url 'https://maven.blamejared.com'
    }
}

dependencies {

    compile "net.darkhax.gamestages:GameStages-${version_minecraft}:${version_gamestages}"
}

Working With Stages

This mod provides a class called GameStageHelper which provides many helper methods and utilities for your mod to use. It is recommended to only access GameStages through this class to ensure that all the right events and hooks get triggered. This mod also provides an extensive list of events that you can use.

Event List

• Add - Fired when a player gets a stage. You can cancel this to prevent the stage from being unlocked.
• Added - Fired after the stage has been added.
• Remove - Fired when a player loses a stage. You can cancel this to prevent the stage from being removed.
• Removed - Fired after the stage was removed.
• Cleared - Fired when the player has had their gamestage data cleared.
• Check - Fired when a check is made on a player's stage data. You can use this event to override the results with your own.
• StagesSyncedEvent - Fired on the client when the stage data has been synched from the client.

Important Notes & Tips

• Whenever you add or remove a stage from a player, you need to manually call the sync method to sync the data to the client.
• The client only knows their own stage data.
• Whenever a user specifies a stage with your mods configuration, you should test the name using GameStageHelper#isStageKnown to ensure the stage is known. If the stage is not known you should assume it's a typo and give an error.
• If you have any questions or requests please reach out to me on Twitter or Discord.