Stage System

Stage System

• By default, when a player first logs into the world, their Stage "container" is completely empty. In this state, every game element associated with a specific Stage is restricted and inaccessible.
• The exact moment a Stage is added to the container, all content, blocks, recipes or permissions associated with that stage are instantly unlocked. This approach gives you absolute control over progression, allowing you to decide exactly whenand how a player can evolve.

Important Rules

It is very important to understand how the framework handles stage registration:

• Implicit Registration (Default): Stages do not need to be defined or registered via code to work. If a stage is simply connected to a game restriction, AStages automatically registers it as a permanent stage.
• AStages#customizeStage: Use this only if you want to change the visual or logical features (like titles, messages or events) of an existing permanent stage.
• AStages#customizeTemporaryStage: This method is MANDATORY if you want a temporary stage: you must explicitly tell the game about it using this method so the framework can set up its duration and behavior.

---

Player Scope & Server Scope

One of the most interesting features of AStages is the logical separation of Stage containers (the Scope). You are not limited to managing individual users; you can manage the entire server.

Scopes are divided into two categories:

• Player-Scope: The Stage is assigned to the individual player's container. Progression is strictly personal and follows the user wherever they go.
• Server-Scope (Global Scope): The Stage is assigned directly to the server. When a Stage is active at the Server level, it is considered globally unlocked for all players, regardless of the contents of their personal container.

Permanent & Temporary Stages

Not all unlocks need to last forever. AStages introduces dynamic Persistence management, differentiating Stage stability based on the required gameplay.

• Permanent Stages (Persistent - Default Behavior)
  • These are standard Stages. Once added to the container (Player or Server), they remain active indefinitely until a command or script explicitly decides to remove them.
• Temporary Stages (Non-persistent)
  • A true game-changer for dynamic gameplay. Temporary Stages allow you to define a validity timer expressed in real time.
  • The countdown of the Stage associated with the player advances only while the player is actually online.
  • When the timer expires, the framework automatically and cleanly removes the Stage from its respective container (be it an individual Player or the Server), instantly restoring the restrictions.

---

In-Game Commands

Main commands to manage stages directly from the game chat (requires operator permissions).

Command	Description	Parameters
/astages add <player> <stage> [<silentChat>] [<silentTitle>]	Adds a stage to a player.	player: player username. stage: stage as string. silentChat: OPTIONAL. If set to true, chat message is not shown. silentTitle: OPTIONAL. If set to true, title and subtitle are not shown.
/astages remove <player> <stage> [<silentChat>] [<silentTitle>]	Removes a stage from the player.	player: player username. stage: stage as string. silentChat: OPTIONAL. If set to true, chat message is not shown. silentTitle: OPTIONAL. If set to true, title and subtitle are not shown.
/astages remove_all <player> [<silentChat>] [<silentTitle>]	Removes all stage from the player's container.	player: player username. silentChat: OPTIONAL. If set to true, chat message is not shown. silentTitle: OPTIONAL. If set to true, title and subtitle are not shown.
/astages info [<player>]	Shows a list of all stages that the player (or the executor) have.	player: OPTIONAL. If the username is omitted, the default player is the executor of the command.
/astages client_info [<player>]	Shows a list of all stages that the player (or the executor) have in the client container.	player: OPTIONAL. If the username is omitted, the default player is the executor of the command.
/astages server add <stage>	Adds a stage to the server.	stage: stage as string.
/astages server remove <stage>	Removes a stage from the server.	stage: stage as string.
/astages server remove_all	Removes all stage from the server's container.	-
/astages server info	Shows a list of all stages that the server have.	-

---

Code Examples

Note

You don't need to set all attributes (properties) for each method: changes should be done only when you want to modify default values!

Basic Usage

// Server Script Folder -> file.js (arbitrary file name).
AStages.customizeStage("stage") // Should NOT be used without changing any property
AStages.customizeStage("stage", "description")

AStages.customizeTemporaryStage("temporary_stage", new ATime("1h3m4s10t")) // h: hours, m: minutes, s: seconds, t: ticks
AStages.customizeTemporaryStage("temporary_stage", "description", new ATime("1h3m4s10t")) // h: hours, m: minutes, s: seconds, t: ticks

Properties (for Permanent Stages)

AStages.customizeStage("stage")
    .serverOnly() // The stage can be added only to the server (and not to the players)
    .playerOnly() // The stage can be added only to the players (and not to the server)
    .titleOnAdd(stage => Component.literal("New title").append(stage).green())
    .subTitleOnAdd(stage => ...)
    .chatMessageOnAdd(stage => ...)
    .titleOnRemove(stage => ...)
    .subTitleOnRemove(stage => ...)
    .chatMessageOnRemove(stage => ...)
    .fadeIn(20) // This is the default value
    .fadeOut(20) // This is the default value
    .stay(60) // This is the default value
    .whenGranted(e => {
        // Those are all methods available for this type of event
        e.getPlayer() // Returns the player
        e.getServer() // Returns the server
        e.isClientSide() // Checks if the action is performed client-side
        e.isPlayerAvailable() // Checks if the player is not null (the stage can be added to the server, so the player can be null)
        e.isServerAvailable() // Checks if the server is not null
    })

Properties (for Temporary Stages)

AStages.customizeTemporaryStage("temporary_stage", new ATime("10m"))
    .serverOnly() // The stage can be added only to the server (and not to the players)
    .playerOnly() // The stage can be added only to the players (and not to the server)
    .titleOnAdd(stage => Component.literal("New title").append(stage).green())
    .subTitleOnAdd(stage => "")
    .chatMessageOnAdd(stage => "")
    .titleOnRemove(stage => "")
    .subTitleOnRemove(stage => "")
    .chatMessageOnRemove(stage => "")
    .fadeIn(20) // This is the default value
    .fadeOut(20) // This is the default value
    .stay(60) // This is the default value
    .whenGranted(e => {
        // Those are all methods available for this type of event
        e.getPlayer() // Returns the player
        e.getServer() // Returns the server
        e.isClientSide() // Checks if the action is performed client-side
        e.isPlayerAvailable() // Checks if the player is not null (the stage can be added to the server, so the player can be null)
        e.isServerAvailable() // Checks if the server is not null
    })
    .everyTick(e => {
        // Those are all methods available for this type of event
        e.getPlayer() // Returns the player
        e.getServer() // Returns the server
        e.isClientSide() // Checks if the action is performed client-side
        e.isPlayerAvailable() // Checks if the player is not null (the stage can be added to the server, so the player can be null)
        e.isServerAvailable() // Checks if the server is not null
    })
    .whenExpired(e => {
        // Those are all methods available for this type of event
        e.getPlayer() // Returns the player
        e.getServer() // Returns the server
        e.isClientSide() // Checks if the action is performed client-side
        e.isPlayerAvailable() // Checks if the player is not null (the stage can be added to the server, so the player can be null)
        e.isServerAvailable() // Checks if the server is not null
    })