switch_device: Player-Flipped State for Doors, Lights & Puzzles

Overview

The switch_device is the classic on/off lever. A player walks up, interacts, and the switch flips between two states — on and off. That single bit of state is incredibly useful: it can power a barrier, reveal a path, flip a light, or be one piece of a multi-switch puzzle (the escape-room circuit-breaker pattern).

Reach for a switch when you want a player-controlled toggle rather than a one-shot button press. Unlike a button, a switch remembers whether it is on or off, can store that state per-player or globally, can persist across sessions, and can auto-reset after a timer. In Verse you don't poll the device — you subscribe to TurnedOnEvent and TurnedOffEvent and run your logic in the handlers, and you call methods like TurnOn, TurnOff, ToggleState, SetState and CheckState to drive or query it from code.

A few key concepts before we code:

• Every state-changing method takes an Agent — the instigator of the action (the player flipping it). Events hand you that agent back.
• GetCurrentState() is a failable query (<decides>): it succeeds when the switch is on and fails when it is off. You use it inside an if.
• The device has a Store State Per Player setting. If it's No, use the no-arg overloads (GetCurrentState(), SetState(State)). If it's Yes, use the agent overloads (GetCurrentState(Agent), SetState(Agent, State)).

API Reference

switch_device

Used to allow agents to turn other linked devices on/off or other custom state changes.

Full public surface, resolved verbatim from the live Epic digest (Fortnite.digest.verse).

switch_device<public> := class<concrete><final>(creative_device_base):

Events (subscribe a handler to react):

Methods (call these to make the device act):

Walkthrough

Let's build a vault door power switch. A player flips a wall switch (the switch_device). When it turns on, we power up a barrier_device so players can pass, play a confirmation audio_player_device, and update the interaction prompt. When it turns off, we slam the barrier back up. We also set a custom interaction time and prompt text in code so the device feels right.

# Vault door controlled by a wall switch.
vault_power_switch := class(creative_device):

    # The wall switch the player interacts with.
    @editable
    PowerSwitch : switch_device = switch_device{}

    # The barrier blocking the vault; we drop it when powered on.
    @editable
    VaultBarrier : barrier_device = barrier_device{}

    # Plays a confirmation sound when power comes on.
    @editable
    PowerOnSound : audio_player_device = audio_player_device{}

    # Localized message helper — `message` params need a localized value.
    PromptText<localizes>(S : string) : message = "{S}"

    OnBegin<override>()<suspends> : void =
        # Configure the switch from code before players touch it.
        PowerSwitch.SetInteractionTime(1.5)
        PowerSwitch.SetTurnOnInteractionText(PromptText("Restore Vault Power"))
        PowerSwitch.SetTurnOffInteractionText(PromptText("Cut Vault Power"))

        # Make sure the door starts sealed.
        VaultBarrier.Enable()

        # React to the player flipping the switch.
        PowerSwitch.TurnedOnEvent.Subscribe(OnPowerOn)
        PowerSwitch.TurnedOffEvent.Subscribe(OnPowerOff)

    # Called when an agent turns the switch ON.
    OnPowerOn(Agent : agent) : void =
        # Drop the barrier so the vault opens.
        VaultBarrier.Disable()
        PowerOnSound.Play(Agent)

    # Called when an agent turns the switch OFF.
    OnPowerOff(Agent : agent) : void =
        # Re-seal the vault.
        VaultBarrier.Enable()

Line by line:

• @editable PowerSwitch : switch_device = switch_device{} — you MUST declare the placed device as an editable field so Verse can talk to the one you dropped in the level. A bare switch_device.TurnOn() would be an Unknown identifier error.
• PromptText<localizes>(S : string) : message — the SetTurnOnInteractionText/SetTurnOffInteractionText methods take a message, not a raw string. This helper wraps a string into a localized message. There is no StringToMessage.
• In OnBegin, SetInteractionTime(1.5) makes the player hold for 1.5 seconds; the two Set...InteractionText calls give context-aware prompts (one shown while off, one while on).
• VaultBarrier.Enable() seals the door at match start.
• PowerSwitch.TurnedOnEvent.Subscribe(OnPowerOn) wires the switch's turned on event to our method. TurnedOnEvent is a listenable(agent), so the handler signature is (Agent : agent).
• OnPowerOn / OnPowerOff are methods at class scope (4-space indent). When power comes on we Disable() the barrier (opening the vault) and Play the sound for the instigating agent; when it goes off we re-Enable() the barrier.

Common patterns

Toggle a switch from another device, and query its state

Here a separate trigger (a pressure plate) toggles the switch, and we read the result with the failable GetCurrentState(). This is a global switch (Store State Per Player = No), so we use the no-arg overloads.

lights_toggle := class(creative_device):

    @editable
    LightSwitch : switch_device = switch_device{}

    @editable
    PressurePlate : trigger_device = trigger_device{}

    OnBegin<override>()<suspends> : void =
        # Each time the plate fires, flip the switch for that player.
        PressurePlate.TriggeredEvent.Subscribe(OnPlateStepped)

    OnPlateStepped(MaybeAgent : ?agent) : void =
        # listenable(?agent) hands an optional agent — unwrap it.
        if (A := MaybeAgent?):
            LightSwitch.ToggleState(A)
            # GetCurrentState() succeeds only when the switch is ON.
            if (LightSwitch.GetCurrentState[]):
                Print("Lights are now ON")
            else:
                Print("Lights are now OFF")

Force a state in code and auto-reset it

Useful for round resets: drive the switch directly with SetState, give it a reset timer with SetStateResetTime, and listen for the change with StateChangesEvent.

round_reset_switch := class(creative_device):

    @editable
    GlobalSwitch : switch_device = switch_device{}

    OnBegin<override>()<suspends> : void =
        # Force the switch OFF at the start of a round (global overload).
        GlobalSwitch.SetState(false)
        # Have it reset itself to default after 30 seconds.
        GlobalSwitch.SetStateResetTime(30.0)
        # React whenever the state changes for any reason.
        GlobalSwitch.StateChangesEvent.Subscribe(OnStateChanged)

    OnStateChanged() : void =
        # StateChangesEvent is listenable(tuple()) — no agent payload.
        Print("Switch state changed; reset countdown is running")

Save & load per-player state (persistence)

When Store State Per Player is Yes, you can persist each player's switch position. Subscribe to StateLoadEvent and use SaveState / LoadState with an agent.

per_player_switch := class(creative_device):

    @editable
    DoorSwitch : switch_device = switch_device{}

    @editable
    JoinTracker : trigger_device = trigger_device{}

    OnBegin<override>()<suspends> : void =
        # When the player's saved state loads, react to it.
        DoorSwitch.StateLoadEvent.Subscribe(OnStateLoaded)
        # Persist whatever the player set when they flip it on.
        DoorSwitch.TurnedOnEvent.Subscribe(OnTurnedOn)

    OnTurnedOn(Agent : agent) : void =
        # Save this player's switch state to persistence.
        DoorSwitch.SaveState(Agent)

    OnStateLoaded(Agent : agent) : void =
        # Per-player overload of GetCurrentState takes the agent.
        if (DoorSwitch.GetCurrentState[Agent]):
            Print("This player's switch loaded ON")
        else:
            Print("This player's switch loaded OFF")

Gotchas

• GetCurrentState is failable, not a getter that returns a bool. It has the <decides> effect: it succeeds if the switch is on and fails if off. Call it inside an if (Switch.GetCurrentState[]): (square brackets for the failable call). There is no GetCurrentState() that returns a logic value.
• Pick the right overload for your Store State Per Player setting. With per-player = No, use GetCurrentState[], SetState(State), GetStateResetTime(). With per-player = Yes, use the agent versions: GetCurrentState[Agent], SetState(Agent, State), GetCurrentResetTime(Agent). Mixing them gives wrong (or empty) results — e.g. GetCurrentResetTime() returns -1.0 when the device is per-player.
• Interaction text must be a message. SetTurnOnInteractionText / SetTurnOffInteractionText won't accept a plain string. Use a <localizes> helper like PromptText<localizes>(S:string):message = "{S}". Text is clamped to 150 characters.
• tuple() events carry no agent. IfOnWhenCheckedEvent, IfOffWhenCheckedEvent, StateChangesEvent, StateSaveEvent are listenable(tuple()) — their handlers take no parameters. Only TurnedOnEvent, TurnedOffEvent, StateLoadEvent and ClearEvent hand you an agent.
• CheckState doesn't return the state — it raises events. Calling CheckState(Agent) fires either IfOnWhenCheckedEvent or IfOffWhenCheckedEvent. Subscribe to those if you trigger checks from code (the escape-room circuit-breaker puzzle reads switch sequences this way).
• Trigger payloads are optional agents. trigger_device.TriggeredEvent is listenable(?agent), so unwrap with if (A := MaybeAgent?): before passing it to ToggleState(A). Switch events themselves are listenable(agent) and need no unwrapping.
• Verse never auto-converts int↔float. SetInteractionTime and SetStateResetTime take float — write 1.5 and 30.0, not 30.