# SugarRush.galaxy
# A script that listens for Halloween Candy consumption and grants a bonus item
# via an item_granter_device when a player interacts with a trigger device.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Characters }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }
using { /Verse.org/Random }

# This is our main "Island" object. Think of it as the manager of our island's logic.
sugar_rush_island := class(creative_device):

    # DEVICE REFERENCES: Wire these up in the UEFN editor to real devices on your map.
    # CandyTrigger detects when a player steps on or interacts with the candy zone.
    @editable
    CandyTrigger : trigger_device = trigger_device{}

    # BonusGranter1 and BonusGranter2 are item_granter_devices placed on the map.
    # Set each one up in the editor to grant whichever item you want.
    @editable
    BonusGranter1 : item_granter_device = item_granter_device{}

    @editable
    BonusGranter2 : item_granter_device = item_granter_device{}

    # OnBegin runs automatically when the island session starts.
    # We use it to subscribe our handler to the trigger's event.
    OnBegin<override>()<suspends> : void =
        # EVENT: subscribe to the trigger so OnCandyTriggered runs
        # whenever a player activates CandyTrigger.
        CandyTrigger.TriggeredEvent.Subscribe(OnCandyTriggered)

    # EVENT: The "Trigger Trap"
    # This function runs automatically whenever the trigger device fires.
    # 'MaybeAgent' is an ?agent — the player who activated the trigger,
    # wrapped in an option type because a trigger can fire without a player.
    OnCandyTriggered(MaybeAgent : ?agent) : void =
        # VARIABLE: The "Inventory Slot"
        # Unwrap the optional agent so we can work with a real player.
        # Think of this like checking the label on a loot box.
        if (Agent := MaybeAgent?):
            # CONDITIONAL: The "Gate Logic"
            # We check which bonus the player should receive.
            # GrantSugarRushBonus picks randomly between our two granters.
            GrantSugarRushBonus(Agent)

    # FUNCTION: The "Helper Device"
    # This function handles the actual item granting.
    # It randomly picks between BonusGranter1 and BonusGranter2 using
    # a coinflip so each call has a 50 % chance of either reward.
    GrantSugarRushBonus(Agent : agent) : void =
        # GetRandomInt returns an integer in [Min, Max] inclusive.
        Roll := GetRandomInt(0, 1)

        # CONDITIONAL: route the grant to whichever device was rolled.
        if (Roll = 0):
            BonusGranter1.GrantItem(Agent)
        else:
            BonusGranter2.GrantItem(Agent)