Skip to content
AbstractMenus AbstractMenus

Counter & Toggle

Two of the most common state primitives in any GUI: a numeric counter that goes up and down, and a binary toggle. Both demo the per-player variable system (varp) and the dual-item pattern for conditional display.

What it teaches

Section titled “What it teaches”
  • incVarp / decVarp / removeVarp for numeric mutations
  • setVarp with the "name::value" shorthand
  • The %varp_:name:default% placeholder syntax
  • The existVarp rule for “does this variable exist for this player”
  • The dual-item pattern: two items at the same slot, the first with rules, the second as fallback
  • refreshMenu: true so the display updates without closing and reopening
intermediate
Features: incVarpdecVarpsetVarpremoveVarpexistVarprefreshMenudual-item-display
Open: /ame_counter 
# Counter & Toggle - personal variable demo
# Docs: https://abstractmenus.github.io/docs/en/examples/state-and-vars/counter-toggle
# Open: /ame_counter
# Requires: -


include required(file("./plugins/AbstractMenus/menus/example/_shared/templates.conf"))


title: "&6Counter & Toggle"
size: 3


activators {
  command: "ame_counter"
}


items: [
  ${borderBlack} { slot: "0-8" }
  ${borderBlack} { slot: "18-26" }


  # ========== Counter section ==========
  # Reset counter
  {
    slot: 10
    material: BARRIER
    name: "&cReset counter"
    lore: ["&7Click to clear the counter."]
    click {
      actions {
        removeVarp: "ame_counter"
        sound: ${clickSound}
        refreshMenu: true
      }
    }
  }


  # Decrement
  {
    slot: 11
    material: RED_WOOL
    name: "&c-1"
    click {
      actions {
        decVarp: "ame_counter"
        sound: ${clickSound}
        refreshMenu: true
      }
    }
  }


  # Counter display - default 0 if var not set
  {
    slot: 12
    material: BOOK
    name: "&6Counter: &e%varp_:ame_counter:0%"
    lore: ["&7Your personal counter, persisted between sessions."]
  }


  # Increment
  {
    slot: 13
    material: GREEN_WOOL
    name: "&a+1"
    click {
      actions {
        incVarp: "ame_counter"
        sound: ${clickSound}
        refreshMenu: true
      }
    }
  }


  # ========== Toggle section ==========
  # Dual-item pattern: first item renders when var exists,
  # second item renders when it doesn't.


  # Toggle ON state (visible only when var exists)
  {
    slot: 15
    material: LIME_DYE
    name: "&aToggle: ON"
    lore: ["&7Click to turn OFF."]
    rules { existVarp: "ame_toggle" }
    click {
      actions {
        removeVarp: "ame_toggle"
        sound: ${clickSound}
        refreshMenu: true
      }
    }
  }


  # Toggle OFF state (fallback, no rules - renders when ON variant hides)
  {
    slot: 15
    material: GRAY_DYE
    name: "&7Toggle: OFF"
    lore: ["&7Click to turn ON."]
    click {
      actions {
        setVarp: "ame_toggle::1"
        sound: ${clickSound}
        refreshMenu: true
      }
    }
  }


  ${buttonClose} { slot: 22 }
]
↓ menu.conf

Bundle includes _shared/templates.conf and INSTALL.txt.

How the counter works

Section titled “How the counter works”

The counter uses three actions and a placeholder:

  • incVarp: "ame_counter" adds 1 to the variable. If it doesn’t exist, the plugin auto-initializes it to 0 first.
  • decVarp: "ame_counter" subtracts 1.
  • removeVarp: "ame_counter" deletes the variable - effectively a reset to “no counter”.

The display item shows %varp_:ame_counter:0%. The :0 suffix is the default value: when the variable doesn’t exist, the placeholder renders as 0 instead of an empty string.

Every click action ends with refreshMenu: true so the display item updates immediately. Without this, the counter would only refresh when the menu’s auto-update interval fires (or never, if updateInterval is unset).

How the toggle works

Section titled “How the toggle works”

The toggle uses the dual-item pattern: two items declared at the same slot, where the first one renders only when its rules pass, and the second one is the fallback.

# Visible when toggle is set
{ slot: 15, material: LIME_DYE, rules { existVarp: "ame_toggle" }, ... }


# Visible when toggle is NOT set
{ slot: 15, material: GRAY_DYE, ... }   # no rules = always passes

When the player has the ame_toggle variable set, the green item shows and clicking it removes the variable. When the variable doesn’t exist, the gray item shows and clicking it sets the variable to “1” (the value doesn’t matter for an existence check, just that the variable exists).

This pattern is heavily used for things like “give item / already claimed”, “VIP price / regular price”, “muted / unmuted” - any binary state where the player should see different visuals.

Customizing

Section titled “Customizing”

To change the variable name, replace ame_counter and ame_toggle everywhere - in the actions, the existVarp rule, and the placeholder. Pick names with a server-specific prefix to avoid collisions with other menus.

For a counter with a step bigger than 1, use the object form:

incVarp: [
  { name: "ame_counter", amount: 5 }
]

Try it

Section titled “Try it”

After installing the example pack:

  1. Drop the bundle into plugins/AbstractMenus/menus/example/.
  2. /am reload.
  3. Type /ame_counter in-game.
  4. Click around. The counter persists - close the menu, reopen, the value is still there.