Game Stages Mod — Guide

Getting Started

To begin using Game Stages, you must first understand how stages are defined and granted.

Stage Naming Rules

Stages are not "registered" in code. They are created the moment they are referenced in a command or script. However, they must follow strict naming conventions: * Length: Maximum 64 characters. * Characters: Only lowercase letters (a-z), numbers (0-9), underscores (_), and colons (:). * No Spaces: Spaces are strictly prohibited.

Granting Stages

The most common way to give a player a stage is through the /gamestage add command. This is typically automated via: 1. Advancements: Using the reward function to run a command when a player completes a task. 2. Quests: Mods like FTB Quests or Better Questing can trigger stage commands as rewards. 3. Scripts: Using CraftTweaker or KubeJS to grant stages based on custom logic (e.g., eating a specific food or reaching a certain level).

Progression Mechanics (Addons)

Since Game Stages is an API, it relies on "Addon Mods" to implement actual gameplay restrictions. Below are the primary ways the game is altered using this framework:

Item & Block Restrictions

Using Item Stages, modpack authors can prevent players from using, holding, or even seeing items. * Restricted Interaction: If a player lacks the stage, the item may be dropped from their inventory or rendered as an "Unfamiliar Item." * Ore Hiding: Ore Stages can replace specific blocks (like Diamond Ore) with Stone until the required stage is reached.

Mob & Combat Restrictions

Mob Stages allows for controlling entity spawning and behavior: * Spawn Control: Prevent Creepers from spawning until the player reaches a certain tier. * Stat Scaling: Mobs can be given extra health or damage if the player has a specific stage.

Dimension & World Restrictions

Dimension Stages prevents players from using portals or entering specific realms (like The Nether or The End) until they have earned the necessary flag.

Developer API

For mod developers, Game Stages provides the GameStageHelper class and several Forge/Fabric events to hook into the progression system.

Event List

• GameStageEvent.Add: Fired before a stage is added. Can be canceled to prevent the unlock.
• GameStageEvent.Added: Fired after a stage has been successfully added.
• GameStageEvent.Remove: Fired before a stage is removed. Can be canceled.
• GameStageEvent.Removed: Fired after a stage is removed.
• GameStageEvent.Check: Fired when the game checks for a stage; allows developers to override the result (e.g., granting a stage temporarily).
• StagesSyncedEvent: Fired on the client side when stage data is received from the server.

Important Implementation Notes

• Manual Syncing: When programmatically adding or removing stages, developers must call the sync method to ensure the client-side UI and logic update correctly.
• Client Limitations: The client only possesses data regarding their own stages; they cannot see the stages of other players for security and performance reasons.

CraftTweaker Integration

Game Stages is deeply integrated with CraftTweaker, allowing for script-based progression logic.

Basic Scripting

You can check for stages within any ZenScript using the following methods:

// Check if a player has a stage
if (player.hasGameStage("stone_age")) {
 print("Player is in the Stone Age!");
}

// Add or Remove stages via script
player.addGameStage("iron_age");
player.removeGameStage("stone_age");

Recipe Locking

With the Recipe Stages addon, you can lock specific recipes to a stage:

// mods.recipestages.Recipes.setRecipeStage(stageName, itemStack);
mods.recipestages.Recipes.setRecipeStage("iron_age", <item:minecraft:iron_ingot>);