Game Stages Mod Wiki

Game Stages is not a content mod in the traditional sense; it is a powerful API and framework designed for modpack creators. It introduces the concept of "Stages"—named flags that act as keys to unlock various parts of the game.

On its own, a stage has no inherent effect. Its power comes from Addon Mods and CraftTweaker scripts that check for these flags before allowing a player to interact with specific items, craft recipes, enter dimensions, or encounter certain mobs. This allows for highly customized progression paths, such as RPG-style classes, age-based technology tiers, or quest-driven unlocks.

Key Features

• Universal API: A centralized system for all mods to share progression data.
• Persistence: Stage data is saved to the player's NBT and survives world restarts.
• Networking: Automatically synchronizes stage data between the server and client.
• Flexibility: Stages are non-linear; players can have any number of stages in any order.

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).

Game Stages provides a robust set of commands for administrators (Op Level 2) and players (Op Level 0) to manage progression data.

The mod uses two primary JSON configuration files located in the ~/config/gamestages/ directory.

Known Stages (known_stages.json)

While stages are created dynamically, listing them here is highly recommended. This file enables tab-completion for commands and prevents typos by issuing warnings for undefined stages.

Example:

[
 "stone_age",
 "iron_age",
 "magic_tier_1"
]

Fake Players (fake_players.json)

Fake players (used by machines and automation mods) cannot naturally unlock stages. This file allows you to define default stages for specific fake player entities so they can interact with staged blocks or items.

Example:

[
 {
 "fakePlayerName": "[BuildCraft]",
 "stages": ["industrial_age"]
 }
]

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.

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>);

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.