Restriction System

Restriction System

If Stages represent the unlock keys in a player's journey, Restrictions are the padlocks placed in the game world. A restriction denies access to a specific mechanic (an item, a dimension, an enchantment) until the player (or the server) obtains the corresponding Stage.

---

How Do You Register a Restriction?

AStages offers you two complementary paths to apply restrictions, adapting to both advanced modpack creators and server administrators:

• Via KubeJS Scripts (Recommended): The most powerful method. It allows you to define complex restrictions at server startup and unlocks full customization of every single attribute.
• Via Simple Restrictions (In-Game): Ideal for quick changes and "on-the-fly" setups. You can add, remove or manage restrictions directly in-game via commands, without touching a line of code or restarting the server.

---

Basic Restriction Parameters

Important

Multiple different restrictions (with different IDs) can be linked to the same Stage. This way, by unlocking a single Stage, the player will remove multiple restrictions simultaneously.

To be valid, every single restriction must be registered with two fundamental and mandatory parameters:

• ID (Unique Identifier): An arbitrary text string that identifies that specific restriction. It must be unique across the entire server to avoid conflicts. Examples of good IDs include diamond_sword, lock_nether_phase_1, ban_fly_enchant or modid:utensils.
• Stage: The name of the Stage required to unlock this restriction.

---

Attributes (Properties)

Each type of restriction is not a simple ON/OFF switch. Each possesses a series of specific Attributes (often referred to interchangeably as Properties) that can be modified individually. This exclusive KubeJS feature allows you to vary the behavior of the same restriction based on precise conditions.

Examples of Using Attributes

Adding properties to your restrictions is very beginner-friendly. In your KubeJS script, you simply "chain" these attributes to the end of your restriction using a dot (.).

There are generally three ways attributes are used, from simplest to most advanced:

• Simple Flags: These just add a behavior without needing extra information.
• Value Properties: These require a specific number, text or item to work.
• Functions: These use a small block of code to create dynamic behaviors, like custom messages.

Here is an example combining all three types:

AStages.addRestrictionForItem("astages/item1", "stage_item", Items.OAK_LOG, "chest")
    // 1. Simple Flag: Allows the player to still use the item to attack
    .allowAttack() 
    
    // 2. Value Property: Sets a 60-tick delay before the item can be picked up
    .pickupDelay(60) 
    
    // 3. Function: Sends a custom green chat message to the player when the item is dropped
    .dropMessage(stack => Component.literal("Custom message for item: ")
        .append(stack.getHoverName())
        .withStyle("green"))

---

Presets

If you are building a large modpack, you might find yourself applying the exact same properties to dozens of different restrictions. To save time and keep your code clean, AStages uses Presets. A Preset is a saved bundle of attributes that you can define once and apply to as many restrictions as you want.

How to Create and Use a Preset

First, you create the preset and define which class it applies to, along with the properties you want it to carry:

// Creating the preset
let itemPreset = AStages.createPresetFor(ABaseItemRestriction)
    .apply(r => r.showTooltip())

Then, you simply attach .withPreset() to your restrictions:

// Applying the preset to a restriction
AStages.addRestrictionForItem("astages/item1", "stage_item", Items.OAK_LOG)
    .withPreset(itemPreset)

Note

You can chain multiple presets to a single restriction by adding multiple entries in .withPreset() methods!

Inheritance

Presets follow standard Java class hierarchies. This means: Generic Base Classes: If you create a preset using a base class (like ABaseItemRestriction), it will automatically apply to all of its subclasses (such as AItemRestriction, AItemTagRestriction, etc.). Specific Classes: If you target a specific subclass, the preset will only work for that exact type. Compatibility Guard: If a preset is assigned to an incompatible restriction type, it will simply be ignored and not applied.

Supported Classes for Presets

Presets can be created for restrictions as well as Stages themselves. Here is the structured breakdown of the available classes:

1. Item Restrictions

• ABaseItemRestriction (Generic Base Class)
• AItemRestriction
• AItemModRestriction
• AItemTagRestriction
• AItemPredicateRestriction

2. Recipe Restrictions

• ABaseRecipeRestriction (Generic Base Class)
• ARecipeRestriction
• ARecipeModRestriction

3. Other Restrictions

• ACropRestriction
• ADimensionRestriction
• AEffectRestriction
• AEnchantRestriction
• ALootRestriction
• AMobRestriction
• AOreRestriction
• APetRestriction
• ARegionRestriction
• AScreenRestriction
• AStructureRestriction

4. Stages

• BaseStage (Generic Base Class)
• Stage
• TemporaryStage